Skip to content

Commit

Permalink
Add cache-only option.
Browse files Browse the repository at this point in the history
  • Loading branch information
@dwsteele
dwsteele committed May 31, 2016
1 parent 08e6b11 commit 5c689c7
Show file tree
Hide file tree
Showing 4 changed files with 229 additions and 179 deletions.
276 changes: 161 additions & 115 deletions doc/doc.pl
View file
Expand Up @@ -16,6 +16,7 @@
use File::Basename qw(dirname);
use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);
use Scalar::Util qw(blessed);
use Storable;

use lib dirname($0) . '/lib';
Expand Down Expand Up @@ -54,6 +55,7 @@ =head1 SYNOPSIS
--deploy Write exe.cache into resource for persistence
--no-exe Should commands be executed when building help? (for testing only)
--no-cache Don't use execution cache
--cache-only Only use the execution cache - don't attempt to generate it
--var Override variables defined in the XML
--doc-path Document path to render (manifest.xml should be located here)
--out Output types (html, pdf, markdown)
Expand All @@ -70,6 +72,7 @@ =head1 SYNOPSIS
my $strLogLevel = 'info';
my $bNoExe = false;
my $bNoCache = false;
my $bCacheOnly = false;
my $oVariableOverride = {};
my $strDocPath;
my @stryOutput;
Expand All @@ -87,160 +90,203 @@ =head1 SYNOPSIS
'no-exe', \$bNoExe,
'deploy', \$bDeploy,
'no-cache', \$bNoCache,
'cache-only', \$bCacheOnly,
'var=s%', $oVariableOverride,
'doc-path=s', \$strDocPath)
or pod2usage(2);

# Display version and exit if requested
if ($bHelp || $bVersion)
####################################################################################################################################
# Run in eval block to catch errors
####################################################################################################################################
eval
{
print BACKREST_NAME . ' ' . $VERSION . " Documentation Builder\n";

if ($bHelp)
# Display version and exit if requested
if ($bHelp || $bVersion)
{
print "\n";
pod2usage();
}
print BACKREST_NAME . ' ' . $VERSION . " Documentation Builder\n";

exit 0;
}
if ($bHelp)
{
print "\n";
pod2usage();
}

# Disable cache when no exe
if ($bNoExe)
{
$bNoCache = true;
}
exit 0;
}

# Set console log level
if ($bQuiet)
{
$strLogLevel = 'error';
}
# Disable cache when no exe
if ($bNoExe)
{
$bNoCache = true;
}

# If no keyword was passed then use default
if (@stryKeyword == 0)
{
@stryKeyword = ('default');
}
# Make sure options are set correctly for deploy
if ($bDeploy)
{
my $strError = 'cannot be specified for deploy';

logLevelSet(undef, uc($strLogLevel));
!$bNoExe
or confess "--no-exe ${strError}";

# Get the base path
my $strBasePath = abs_path(dirname($0));
!$bNoCache
or confess "--no-cache ${strError}";

if (!defined($strDocPath))
{
$strDocPath = $strBasePath;
}
!@stryRequire
or confess "--require ${strError}";

my $strOutputPath = "${strDocPath}/output";
!@stryOutput
or confess "--out ${strError}";
}

# Create the out path if it does not exist
if (!-e $strOutputPath)
{
mkdir($strOutputPath)
or confess &log(ERROR, "unable to create path ${strOutputPath}");
}
# Set console log level
if ($bQuiet)
{
$strLogLevel = 'error';
}

# Load the manifest
my $oManifest;
my $strManifestCache = "${strBasePath}/resource/manifest.cache";
# If no keyword was passed then use default
if (@stryKeyword == 0)
{
@stryKeyword = ('default');
}

$oManifest = new BackRestDoc::Common::DocManifest(\@stryKeyword, \@stryRequire, $oVariableOverride, $strDocPath);
logLevelSet(undef, uc($strLogLevel));

if (!$bNoCache)
{
$oManifest->cacheRead($bDeploy);
}
# Get the base path
my $strBasePath = abs_path(dirname($0));

# If no outputs were given
if (@stryOutput == 0)
{
@stryOutput = $oManifest->renderList();

if ($oManifest->isBackRest())
if (!defined($strDocPath))
{
push(@stryOutput, 'help');
push(@stryOutput, 'man');
$strDocPath = $strBasePath;
}
}

for my $strOutput (@stryOutput)
{
if (!(($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest()))
my $strOutputPath = "${strDocPath}/output";

# Create the out path if it does not exist
if (!-e $strOutputPath)
{
$oManifest->renderGet($strOutput);
mkdir($strOutputPath)
or confess &log(ERROR, "unable to create path ${strOutputPath}");
}

&log(INFO, "render ${strOutput} output");
# Load the manifest
my $oManifest;
my $strManifestCache = "${strBasePath}/resource/manifest.cache";

if ($strOutput eq 'markdown')
$oManifest =
new BackRestDoc::Common::DocManifest(\@stryKeyword, \@stryRequire, $oVariableOverride, $strDocPath, $bDeploy, $bCacheOnly);

if (!$bNoCache)
{
my $oMarkdown =
new BackRestDoc::Markdown::DocMarkdown
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/markdown",
!$bNoExe
);

$oMarkdown->process();
$oManifest->cacheRead();
}
elsif (($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest())

# If no outputs were given
if (@stryOutput == 0)
{
# Generate the command-line help
my $oRender = new BackRestDoc::Common::DocRender('text', $oManifest);
my $oDocConfig =
new BackRestDoc::Common::DocConfig(
new BackRestDoc::Common::Doc("${strBasePath}/xml/reference.xml"), $oRender);
@stryOutput = $oManifest->renderList();

if ($oManifest->isBackRest())
{
push(@stryOutput, 'help');
push(@stryOutput, 'man');
}
}

if ($strOutput eq 'help')
for my $strOutput (@stryOutput)
{
if (!(($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest()))
{
$oDocConfig->helpDataWrite($oManifest);
$oManifest->renderGet($strOutput);
}
else

&log(INFO, "render ${strOutput} output");

if ($strOutput eq 'markdown')
{
filePathCreate("${strBasePath}/output/man", '0770', true, true);
fileStringWrite("${strBasePath}/output/man/" . lc(BACKREST_NAME) . '.1.txt', $oDocConfig->manGet($oManifest), false);
my $oMarkdown =
new BackRestDoc::Markdown::DocMarkdown
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/markdown",
!$bNoExe
);

$oMarkdown->process();
}
elsif (($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest())
{
# Generate the command-line help
my $oRender = new BackRestDoc::Common::DocRender('text', $oManifest);
my $oDocConfig =
new BackRestDoc::Common::DocConfig(
new BackRestDoc::Common::Doc("${strBasePath}/xml/reference.xml"), $oRender);

if ($strOutput eq 'help')
{
$oDocConfig->helpDataWrite($oManifest);
}
else
{
filePathCreate("${strBasePath}/output/man", '0770', true, true);
fileStringWrite("${strBasePath}/output/man/" . lc(BACKREST_NAME) . '.1.txt', $oDocConfig->manGet($oManifest), false);
}
}
elsif ($strOutput eq 'html')
{
my $oHtmlSite =
new BackRestDoc::Html::DocHtmlSite
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/html",
"${strBasePath}/resource/html/default.css",
defined($oManifest->variableGet('project-favicon')) ?
"${strBasePath}/resource/html/" . $oManifest->variableGet('project-favicon') : undef,
defined($oManifest->variableGet('project-logo')) ?
"${strBasePath}/resource/" . $oManifest->variableGet('project-logo') : undef,
!$bNoExe
);

$oHtmlSite->process();
}
elsif ($strOutput eq 'pdf')
{
my $oLatex =
new BackRestDoc::Latex::DocLatex
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/latex",
"${strBasePath}/resource/latex/preamble.tex",
!$bNoExe
);

$oLatex->process();
}
}
elsif ($strOutput eq 'html')

# Cache the manifest (mostly useful for testing rendering changes in the code)
if (!$bNoCache)
{
my $oHtmlSite =
new BackRestDoc::Html::DocHtmlSite
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/html",
"${strBasePath}/resource/html/default.css",
defined($oManifest->variableGet('project-favicon')) ?
"${strBasePath}/resource/html/" . $oManifest->variableGet('project-favicon') : undef,
defined($oManifest->variableGet('project-logo')) ?
"${strBasePath}/resource/" . $oManifest->variableGet('project-logo') : undef,
!$bNoExe
);

$oHtmlSite->process();
$oManifest->cacheWrite();
}
elsif ($strOutput eq 'pdf')
};

####################################################################################################################################
# Check for errors
####################################################################################################################################
if ($@)
{
my $oMessage = $@;

# If a backrest exception then return the code - don't confess
if (blessed($oMessage) && $oMessage->isa('pgBackRest::Common::Exception'))
{
my $oLatex =
new BackRestDoc::Latex::DocLatex
(
$oManifest,
"${strBasePath}/xml",
"${strOutputPath}/latex",
"${strBasePath}/resource/latex/preamble.tex",
!$bNoExe
);

$oLatex->process();
exit $oMessage->code();
}
}

# Cache the manifest (mostly useful for testing rendering changes in the code)
if (!$bNoCache)
{
$oManifest->cacheWrite($bDeploy);
confess $oMessage;
}
7 changes: 7 additions & 0 deletions doc/lib/BackRestDoc/Common/DocExecute.pm
View file
Expand Up @@ -818,6 +818,13 @@ sub cachePop
$oCacheValue = $$hCache{value};
$self->{iCacheIdx}++;
}
else
{
if ($self->{oManifest}{bCacheOnly})
{
confess &log(ERROR, 'Cache only operation forced by --cache-only option');
}
}

# Return from function and log return values if any
return logDebugReturn
Expand Down

0 comments on commit 5c689c7

Please sign in to comment.