Pre-build containers for any execute elements marked pre.

This allows the documentation to be built more quickly and offline during development when --pre is specified on the command line.

Each host gets a pre-built container with all the execute elements marked pre. As long as the pre elements do not change the container will not need to be rebuilt.

The feature should not be used for CI builds as it may hide errors in the documentation.

doc/lib/BackRestDoc/Common/DocExecute.pm

@@ -259,7 +259,8 @@ sub execute
 
     &log(DEBUG, ('    ' x $iIndent) . "execute: $strCommand");
 
-    if ($self->{oManifest}->variableReplace($oCommand->paramGet('skip', false, 'n')) ne 'y')
+    if ($self->{oManifest}->variableReplace($oCommand->paramGet('skip', false, 'n')) ne 'y' ||
+        $oCommand->paramGet('pre', false, 'n') eq 'y' && $self->{oManifest}->{bPre})
     {
         if ($self->{bExe} && $self->isRequired($oSection))
         {
@@ -1037,8 +1038,51 @@ sub sectionChildProcess
                 executeTest("rm -rf ~/data/$$hCacheKey{name}");
                 executeTest("mkdir -p ~/data/$$hCacheKey{name}/etc");
 
+                my $strHost = $hCacheKey->{name};
+                my $strImage = $hCacheKey->{image};
+
+                # Determine if a pre-built image should be created
+                if (defined($self->preExecute($strHost)))
+                {
+                    my $strPreImage = "${strImage}-${strHost}";
+                    my $strFrom = $strImage;
+
+                    &log(INFO, "Build vm '${strPreImage}' from '${strFrom}'");
+
+                    my $strCommandList;
+
+                    # Add all pre commands
+                    foreach my $oExecute ($self->preExecute($strHost))
+                    {
+                        my $hExecuteKey = $self->executeKey($strHost, $oExecute);
+                        my $strCommand =
+                            join("\n", @{$hExecuteKey->{cmd}}) .
+                            (defined($hExecuteKey->{'cmd-extra'}) ? ' ' . $hExecuteKey->{'cmd-extra'} : '');
+
+                        if (defined($strCommandList))
+                        {
+                            $strCommandList .= "\n";
+                        }
+
+                        $strCommandList .= "RUN ${strCommand}";
+
+                        &log(DETAIL, "    Pre command $strCommand");
+                    }
+
+                    # Build container
+                    my $strDockerfile = $self->{oManifest}{strDocPath} . "/output/doc-host.dockerfile";
+
+                    $self->{oManifest}{oStorage}->put(
+                        $strDockerfile,
+                        "FROM ${strFrom}\n\n" . trim($self->{oManifest}->variableReplace($strCommandList)) . "\n");
+                    executeTest("docker build -f ${strDockerfile} -t ${strPreImage} " . $self->{oManifest}{oStorage}->pathGet());
+
+                    # Use the pre-built image
+                    $strImage = $strPreImage;
+                }
+
                 my $oHost = new pgBackRestTest::Common::HostTest(
-                    $$hCacheKey{name}, "doc-$$hCacheKey{name}", $$hCacheKey{image},
+                    $$hCacheKey{name}, "doc-$$hCacheKey{name}", $strImage,
                     $self->{oManifest}->variableReplace($oChild->paramGet('user')), $$hCacheKey{os},
                     defined($oChild->paramGet('mount', false)) ?
                         [$self->{oManifest}->variableReplace($oChild->paramGet('mount'))] : undef,

doc/lib/BackRestDoc/Common/DocManifest.pm

@@ -64,6 +64,7 @@ sub new
         $self->{strDocPath},
         $self->{bDeploy},
         $self->{bCacheOnly},
+        $self->{bPre},
     ) =
         logDebugParam
         (
@@ -77,6 +78,7 @@ sub new
             {name => 'strDocPath', required => false},
             {name => 'bDeploy', required => false},
             {name => 'bCacheOnly', required => false},
+            {name => 'bPre', required => false, default => false},
         );
 
     # Set the bin path

doc/lib/BackRestDoc/Common/DocRender.pm

@@ -306,6 +306,22 @@ sub variableGet
     return $self->{oManifest}->variableGet(shift);
 }
 
+####################################################################################################################################
+# Get pre-execute list for a host
+####################################################################################################################################
+sub preExecute
+{
+    my $self = shift;
+    my $strHost = shift;
+
+    if (defined($self->{preExecute}{$strHost}))
+    {
+        return @{$self->{preExecute}{$strHost}};
+    }
+
+    return;
+}
+
 ####################################################################################################################################
 # build
 #
@@ -337,6 +353,7 @@ sub build
             &log(DEBUG, "            filtered ${strName}" . (defined($strDescription) ? ": ${strDescription}" : ''));
 
             $oParent->nodeRemove($oNode);
+            return;
         }
     }
     else
@@ -527,6 +544,16 @@ sub build
             $iChildIdx++;
         }
     }
+    # Check for pre-execute statements
+    elsif ($strName eq 'execute')
+    {
+        if ($self->{oManifest}->{bPre} && $oNode->paramGet('pre', false, 'n') eq 'y')
+        {
+            # Add to pre-execute list
+            my $strHost = $self->variableReplace($oParent->paramGet('host'));
+            push(@{$self->{preExecute}{$strHost}}, $oNode);
+        }
+    }
 
     # Iterate all text nodes
     if (defined($oNode->textGet(false)))
@@ -548,7 +575,7 @@ sub build
             $self->build($oChild, $oNode, $strPath, $strPathPrefix);
 
             # If the child should be logged then log the parent as well so the hierarchy is complete
-            if ($oChild->nameGet() eq 'section' && $oChild->paramGet('log'))
+            if ($oChild->nameGet() eq 'section' && $oChild->paramGet('log', false, false))
             {
                 $oNode->paramSet('log', true);
             }