db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-01-18 04:58:51 +02:00
Code Issues Releases Activity

Improved support for --require option and section depends now default to the previous section.

Browse Source
This commit is contained in:
David Steele 2017-02-11 10:26:54 -05:00
parent 498f52da09
commit d68b48d19b
8 changed files with 108 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/doc.pl
View File

@ -155,6 +155,12 @@ eval
or confess "--require ${strError}";
}
# one --include must be specified when --required is
if (@stryRequire && @stryInclude != 1)
{
confess "one --include is required when --require is specified";
}
# Set console log level
if ($bQuiet)
{

2
doc/lib/BackRestDoc/Common/DocManifest.pm
View File

@ -577,8 +577,6 @@ sub renderOutGet
{name => 'bIgnoreMissing', default => false, trace => true},
);
# use Data::Dumper; print Dumper(${$self->{oManifest}}{render});
if (!defined(${$self->{oManifest}}{render}{$strType}{out}{$strKey}) && !$bIgnoreMissing)
{
confess &log(ERROR, "render out ${strKey} does not exist");

84
doc/lib/BackRestDoc/Common/DocRender.pm
View File

@ -239,6 +239,11 @@ sub new
confess &log(ERROR, "path ${strPath} must begin with a /");
}
if (!defined($self->{oSection}->{$strPath}))
{
confess &log(ERROR, "required section '${strPath}' does not exist");
}
if (defined(${$self->{oSection}}{$strPath}))
{
$self->required($strPath);
@ -340,7 +345,8 @@ sub build
# Build section
if ($strName eq 'section')
{
&log(DEBUG, 'build section [' . $oNode->paramGet('id') . ']');
my $strSectionId = $oNode->paramGet('id');
&log(DEBUG, "build section [${strSectionId}]");
# Set path and parent-path for this section
if (defined($strPath))
@ -354,6 +360,78 @@ sub build
${$self->{oSection}}{$strPath} = $oNode;
$oNode->paramSet('path', $strPath);
# If depend is not set then set it to the last section
my $strDepend = $oNode->paramGet('depend', false);
my $oContainerNode = defined($oParent) ? $oParent : $self->{oDoc};
my $oLastChild;
my $strDependPrev;
foreach my $oChild ($oContainerNode->nodeList('section', false))
{
if ($oChild->paramGet('id') eq $oNode->paramGet('id'))
{
if (defined($oLastChild))
{
$strDependPrev = $oLastChild->paramGet('id');
}
elsif (defined($oParent->paramGet('depend', false)))
{
$strDependPrev = $oParent->paramGet('depend');
}
last;
}
$oLastChild = $oChild;
}
if (defined($strDepend))
{
if (defined($strDependPrev) && $strDepend eq $strDependPrev && !$oNode->paramTest('depend-default'))
{
&log(WARN,
"section '${strPath}' depend is set to '${strDepend}' which is the default, best to remove" .
" because it may become obsolete if a new section is added in between");
}
}
else
{
$strDepend = $strDependPrev;
}
# If depend is defined make sure it exists
if (defined($strDepend))
{
# If this is a relative depend then prepend the parent section
if (index($strDepend, '/') != 0)
{
if (defined($oParent->paramGet('path', false)))
{
$strDepend = $oParent->paramGet('path') . '/' . $strDepend;
}
else
{
$strDepend = "/${strDepend}";
}
}
if (!defined($self->{oSection}->{$strDepend}))
{
confess &log(ERROR, "section '${strSectionId}' depend '${strDepend}' is not valid");
}
}
if (defined($strDepend))
{
$oNode->paramSet('depend', $strDepend);
}
if (defined($strDependPrev))
{
$oNode->paramSet('depend-default', $strDependPrev);
}
# If section content is being pulled from elsewhere go get the content
if ($oNode->paramTest('source'))
{
@ -394,8 +472,6 @@ sub build
$self->{oyBlockDefine}{$strBlockId} = dclone($oNode->{oDoc}{children});
$oParent->nodeRemove($oNode);
# use Data::Dumper; confess "DATA" . Dumper($self->{oyBlockDefine});
# confess "GOT HERE";
}
# Copy blocks
elsif ($strName eq 'block')
@ -484,7 +560,7 @@ sub required
{
if (!defined(${$self->{oSectionRequired}}{$strChildPath}))
{
&log(INFO, " require section: ${strChildPath}");
&log(INFO, (' ' x (scalar(split('/', $strChildPath)) - 2)) . " require section: ${strChildPath}");
${$self->{oSectionRequired}}{$strChildPath} = true;
}

4
doc/lib/BackRestDoc/Html/DocHtmlPage.pm
View File

@ -126,7 +126,7 @@ sub process
{
my $oMenuBody = $oHtmlBuilder->bodyGet()->addNew(HTML_DIV, 'page-menu')->addNew(HTML_DIV, 'menu-body');
if ($self->{strRenderOutKey} ne 'index')
if ($self->{strRenderOutKey} ne 'index' && defined($self->{oManifest}->renderOutGet(RENDER_TYPE_HTML, 'index', true)))
{
my $oRenderOut = $self->{oManifest}->renderOutGet(RENDER_TYPE_HTML, 'index');
@ -219,7 +219,7 @@ sub sectionProcess
{name => 'iDepth'}
);
&log($iDepth == 1 ? INFO : DEBUG, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
&log(INFO, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
if ($iDepth > 3)
{

2
doc/lib/BackRestDoc/Latex/DocLatexSection.pm
View File

@ -111,7 +111,7 @@ sub sectionProcess
{name => 'iDepth'}
);
&log($iDepth == 1 ? INFO : DEBUG, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
&log(INFO, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
# Create the section
my $strSectionTitle = $self->processText($oSection->nodeGet('title')->textGet());

2
doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm
View File

@ -176,7 +176,7 @@ sub sectionProcess
{name => 'iDepth'}
);
&log($iDepth == 1 ? INFO : DEBUG, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
&log(INFO, (' ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
if ($iDepth > 3)
{

4
doc/xml/release.xml
View File

@ -163,6 +163,10 @@
<p>Documentation can now be built with reusable blocks to reduce duplication.</p>
</release-item>
<release-item>
<p>Improved support for <setting>--require</setting> option and section depends now default to the previous section.</p>
</release-item>
<release-item>
<p>Added ability to pass options to containers within the documentation.</p>
</release-item>

29
doc/xml/user-guide.xml
View File

@ -263,13 +263,13 @@
</section>
<!-- SECTION => QUICKSTART -->
<section id="quickstart" depend="installation">
<section id="quickstart">
<title>Quick Start</title>
<p>The Quick Start section will cover basic configuration of <backrest/> and <postgres/> and introduce the <cmd>backup</cmd>, <cmd>restore</cmd>, and <cmd>info</cmd> commands.</p>
<!-- SECTION => QUICKSTART - SETUP DEMO CLUSTER -->
<section id="setup-demo-cluster">
<section id="setup-demo-cluster" depend="/quickstart">
<title>Setup Demo Cluster</title>
<p>Creating the demo cluster is optional but is strongly recommended, especially for new users, since the example commands in the user guide reference the demo cluster; the examples assume the demo cluster is running on the default port (i.e. 5432). The cluster will not be started until a later section because there is still some configuration to do.</p>
@ -313,7 +313,7 @@
</section>
<!-- SECTION => QUICKSTART - CONFIGURE STANZA -->
<section id="configure-stanza" depend="setup-demo-cluster">
<section id="configure-stanza">
<title>Configure Cluster Stanza</title>
<option-description key="stanza"/>
@ -339,7 +339,7 @@
</section>
<!-- SECTION => QUICKSTART - CREATE REPOSITORY -->
<section id="create-repository" depend="configure-stanza">
<section id="create-repository">
<title>Create the Repository</title>
<option-description key="repo-path"/>
@ -370,7 +370,7 @@
</section>
<!-- SECTION => QUICKSTART - CONFIGURE ARCHIVING -->
<section id="configure-archiving" depend="create-repository">
<section id="configure-archiving">
<title>Configure Archiving</title>
<p>Backing up a running <postgres/> cluster requires WAL archiving to be enabled. Note that <i>at least</i> one WAL segment will be created during the backup process even if no explicit writes are made to the cluster.</p>
@ -404,7 +404,7 @@
</section>
<!-- SECTION => QUICKSTART - RETENTION -->
<section id="retention" depend="configure-archiving">
<section id="retention">
<title>Configure Retention</title>
<p><backrest/> expires backups based on retention options.</p>
@ -419,7 +419,7 @@
</section>
<!-- SECTION => QUICKSTART - STANZA CREATE -->
<section id="create-stanza" depend="retention">
<section id="create-stanza">
<title>Create the Stanza</title>
<p>The <cmd>stanza-create</cmd> command must be run on the host where the repository is located to initialize the stanza. It is recommended that the <cmd>check</cmd> command be run after <cmd>stanza-create</cmd> to ensure archiving and backups are properly configured.</p>
@ -435,7 +435,7 @@
</section>
<!-- SECTION => QUICKSTART - CHECK CONFIGURATION -->
<section id="check-configuration" depend="create-stanza">
<section id="check-configuration">
<title>Check the Configuration</title>
<cmd-description key="check"/>
@ -460,7 +460,7 @@
</section>
<!-- SECTION => QUICKSTART - PERFORM BACKUP -->
<section id="perform-backup" depend="check-configuration">
<section id="perform-backup">
<title>Perform a Backup</title>
<p>To perform a backup of the <postgres/> cluster run <backrest/> with the <cmd>backup</cmd> command.</p>
@ -784,7 +784,7 @@
</section>
<!-- SECTION => RETENTION - DIFF -->
<section id="diff" depend="full">
<section id="diff">
<title>Differential Backup Retention</title>
<p>Set <br-option>retention-diff</br-option> to the number of differential backups required. Differentials only rely on the prior full backup so it is possible to create a <quote>rolling</quote> set of differentials for the last day or more. This allows quick restores to recent points-in-time but reduces overall space consumption.</p>
@ -827,7 +827,7 @@
</section>
<!-- SECTION => RETENTION - ARCHIVE -->
<section id="archive" depend="diff">
<section id="archive">
<title>Archive Retention</title>
<p>Although <backrest/> automatically removes archived WAL segments when expiring backups (the default expires WAL for full backups based on the <br-option>retention-full</br-option> option), it may be useful to expire archive more aggressively to save disk space. Note that full backups are treated as differential backups for the purpose of differential archive retention.</p>
@ -1412,11 +1412,10 @@
<exe-cmd>{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} check</exe-cmd>
</execute>
</execute-list>
</section>
<!-- SECTION => BACKUP HOST - PERFORM BACKUP -->
<section id="perform-backup" depend="install-config">
<section id="perform-backup">
<title>Perform a Backup</title>
<p>To perform a backup of the <postgres/> cluster run <backrest/> with the <cmd>backup</cmd> command on the <host>backup</host> host.</p>
@ -1433,7 +1432,7 @@
</section>
<!-- SECTION => BACKUP HOST - PERFORM RESTORE -->
<section id="perform-restore" depend="perform-backup">
<section id="perform-restore">
<title>Restore a Backup</title>
<p>To perform a restore of the <postgres/> cluster run <backrest/> with the <cmd>restore</cmd> command on the <host>database</host> host.</p>
@ -1866,7 +1865,7 @@
</section>
<!-- SECTION => REPLICATION - STREAMING -->
<section id="streaming" depend="hot-standby">
<section id="streaming">
<title>Streaming Replication</title>
<p>Instead of relying solely on the WAL archive, streaming replication makes a direct connection to the master and applies changes as soon as they are made on the master. This results in much less lag between the master and standby.</p>