From d68b48d19b53727bafd55e97cde41db309763daa Mon Sep 17 00:00:00 2001 From: David Steele Date: Sat, 11 Feb 2017 10:26:54 -0500 Subject: [PATCH] Improved support for --require option and section depends now default to the previous section. --- doc/doc.pl | 6 ++ doc/lib/BackRestDoc/Common/DocManifest.pm | 2 - doc/lib/BackRestDoc/Common/DocRender.pm | 84 ++++++++++++++++++- doc/lib/BackRestDoc/Html/DocHtmlPage.pm | 4 +- doc/lib/BackRestDoc/Latex/DocLatexSection.pm | 2 +- .../BackRestDoc/Markdown/DocMarkdownRender.pm | 2 +- doc/xml/release.xml | 4 + doc/xml/user-guide.xml | 29 ++++--- 8 files changed, 108 insertions(+), 25 deletions(-) diff --git a/doc/doc.pl b/doc/doc.pl index 88a223040..7adbc058a 100755 --- a/doc/doc.pl +++ b/doc/doc.pl @@ -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) { diff --git a/doc/lib/BackRestDoc/Common/DocManifest.pm b/doc/lib/BackRestDoc/Common/DocManifest.pm index f81f7f404..40419fe49 100644 --- a/doc/lib/BackRestDoc/Common/DocManifest.pm +++ b/doc/lib/BackRestDoc/Common/DocManifest.pm @@ -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"); diff --git a/doc/lib/BackRestDoc/Common/DocRender.pm b/doc/lib/BackRestDoc/Common/DocRender.pm index 955cebadd..5c7b584c4 100644 --- a/doc/lib/BackRestDoc/Common/DocRender.pm +++ b/doc/lib/BackRestDoc/Common/DocRender.pm @@ -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; } diff --git a/doc/lib/BackRestDoc/Html/DocHtmlPage.pm b/doc/lib/BackRestDoc/Html/DocHtmlPage.pm index 929c6be52..65be9c469 100644 --- a/doc/lib/BackRestDoc/Html/DocHtmlPage.pm +++ b/doc/lib/BackRestDoc/Html/DocHtmlPage.pm @@ -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) { diff --git a/doc/lib/BackRestDoc/Latex/DocLatexSection.pm b/doc/lib/BackRestDoc/Latex/DocLatexSection.pm index c9d90a4d7..cd43a5849 100644 --- a/doc/lib/BackRestDoc/Latex/DocLatexSection.pm +++ b/doc/lib/BackRestDoc/Latex/DocLatexSection.pm @@ -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()); diff --git a/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm b/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm index bd69a3058..cd4832a4b 100644 --- a/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm +++ b/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm @@ -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) { diff --git a/doc/xml/release.xml b/doc/xml/release.xml index a4bd62804..009b36ccb 100644 --- a/doc/xml/release.xml +++ b/doc/xml/release.xml @@ -163,6 +163,10 @@

Documentation can now be built with reusable blocks to reduce duplication.

+ +

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

+ +

Added ability to pass options to containers within the documentation.

 diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml index 4cfa800d8..fb8646ec1 100644 --- a/doc/xml/user-guide.xml +++ b/doc/xml/user-guide.xml @@ -263,13 +263,13 @@ -
+
Quick Start

The Quick Start section will cover basic configuration of and and introduce the backup, restore, and info commands.

-
+
Setup Demo Cluster

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.

@@ -313,7 +313,7 @@
-
+
Configure Cluster Stanza @@ -339,7 +339,7 @@
-
+
Create the Repository @@ -370,7 +370,7 @@
-
+
Configure Archiving

Backing up a running cluster requires WAL archiving to be enabled. Note that at least one WAL segment will be created during the backup process even if no explicit writes are made to the cluster.

@@ -404,7 +404,7 @@
-
+
Configure Retention

expires backups based on retention options.

@@ -419,7 +419,7 @@
-
+
Create the Stanza

The stanza-create command must be run on the host where the repository is located to initialize the stanza. It is recommended that the check command be run after stanza-create to ensure archiving and backups are properly configured.

@@ -435,7 +435,7 @@
-
+
Check the Configuration @@ -460,7 +460,7 @@
-
+
Perform a Backup

To perform a backup of the cluster run with the backup command.

@@ -784,7 +784,7 @@
-
+
Differential Backup Retention

Set retention-diff to the number of differential backups required. Differentials only rely on the prior full backup so it is possible to create a rolling set of differentials for the last day or more. This allows quick restores to recent points-in-time but reduces overall space consumption.

@@ -827,7 +827,7 @@
-
+
Archive Retention

Although automatically removes archived WAL segments when expiring backups (the default expires WAL for full backups based on the retention-full 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.

@@ -1412,11 +1412,10 @@ {[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} check -
-
+
Perform a Backup

To perform a backup of the cluster run with the backup command on the backup host.

@@ -1433,7 +1432,7 @@
-
+
Restore a Backup

To perform a restore of the cluster run with the restore command on the database host.

@@ -1866,7 +1865,7 @@
-
+
Streaming Replication

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.