1
0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-12 10:04:14 +02:00
Commit Graph

55 Commits

Author SHA1 Message Date
David Steele
1eb0162208 Build command and configuration reference in C.
Migrate generation of these files from help.xml to the intermediate documentation format. This allows us to share a lot of code that is already in C and remove duplicated code in Perl. More duplicate code can be removed in Perl once man generation is migrated.

Also update the unit test harness to allow testing of modules in the doc directory.
2023-10-09 14:03:43 -04:00
David Steele
f716e98ad0 Suppress errors when there is stderr output for Docker builds.
Docker outputs build info to stderr even when the build is successful. This seems to be especially true on Mac M1.

ContainerTest.pm already does this suppression so add it the other places where containers are built.
2022-02-26 11:31:52 -06:00
David Steele
f4e1babf6b Migrate command-line help generation to C.
Command-line help is now generated at build time so it does not need to be committed. This reduces churn on commits that add configuration and/or update the help.

Since churn is no longer an issue, help.auto.c is bzip2 compressed to save space in the binary.

The Perl config parser (Data.pm) has been moved to doc/lib since the Perl build path is no longer required.

Likewise doc/xml/reference.xml has been moved to src/build/help/help.xml since it is required at build time.
2021-09-08 18:16:06 -04:00
David Steele
4a5bd002c0 Move pgBackRest::Version module to pgBackRestDoc::ProjectInfo.
The primary source for project info is now src/version.h.

The pgBackRestDoc::ProjectInfo module loads the project info from src/version.h at runtime so there is no need to update it.
2020-03-10 17:57:02 -04:00
David Steele
731b862e6f Rename BackRestDoc Perl module to pgBackRestDoc.
This is consistent with the way BackRest and BackRest test were renamed way back in 18fd2523.

More modules will be moving to pgBackRestDoc soon so renaming now reduces churn later.
2020-03-10 15:41:56 -04:00
David Steele
36d4ab9bff Move Perl modules out of lib directory.
This directory was once the home of the production Perl code but since f0ef73db this is no longer true.

Move the modules to test in most cases, except where the module is expected to be useful for the doc engine beyond the expected lifetime of the Perl test code (about a year if all goes well).

The exception is pgBackRest::Version which requires more work to migrate since it is used to track pgBackRest versions.
2020-03-10 15:12:44 -04:00
Josh Soref
545ccfa878 Fix typos in the documentation.
Contributed by Josh Soref.
2019-08-26 12:26:00 -04:00
David Steele
0a96a2895d Add storage layer for tests and documentation.
The tests and documentation have been using the core storage layer but soon that will depend entirely on the C library, creating a bootstrap problem (i.e. the storage layer will be needed to build the C library).

Create a simplified Posix storage layer to be used by documentation and the parts of the test code that build and execute the actual tests.  The actual tests will still use the core storage driver so they can interact with any type of storage.
2019-06-17 09:16:44 -04:00
David Steele
a4561dc087 Add --out-preserve to preserve contents of output path.
Useful for building a single set of documentation over multiple doc.pl runs.
2019-05-16 07:29:17 -04:00
David Steele
bc30027d73 Fix typo in doc.pl command-line help. 2019-05-16 07:04:28 -04:00
David Steele
fdc76742c8 Use absolute paths so that ./doc.pl runs.
The relative paths used would not correctly find required libraries and DTD files.
2018-12-12 13:48:31 -05:00
David Steele
17e611cb88 Replace keywords with more flexible if statements.
Keywords were extremely limited and prevented us from generating multi-version documentation and other improvements.

Replace keywords with an if statement that can evaluate a Perl expression with variable replacement.

Since keywords were used to generate cache keys, add a --key-var parameter to identify which variables should make up the key.
2018-12-01 12:40:01 -05:00
David Steele
5d3c8e47f1 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.
2018-11-29 14:45:15 -05:00
David Steele
801e2a5a2c Rename PGBACKREST/BACKREST constants to PROJECT.
This brings consistency between the C and Perl constants and allows for easier code reuse.
2018-11-24 19:05:03 -05:00
David Steele
2723831032 Allow containers to be defined in a document.
The defined containers are built before the document build begins which allows them to be reused.
2018-07-23 07:49:15 -04:00
David Steele
b58a45e067 Implement help command in C. 2018-01-23 13:34:24 -05:00
David Steele
904b83747c Perl error handler recognizes errors thrown from the C library. 2017-10-16 10:47:31 -04:00
David Steele
1e0ed07455 Configuration rules are now pulled from the C library when present. 2017-08-25 16:47:47 -04:00
David Steele
97c4d9ec18 Reduce log verbosity in doc.pl.
Reduce verbosity by only logging sections that contain an execute list directly or in a child section.
2017-07-26 10:22:22 -04:00
David Steele
de7fc37f88 Storage and IO layer refactor:
Refactor storage layer to allow for new repository filesystems using drivers. (Reviewed by Cynthia Shang.)
Refactor IO layer to allow for new compression formats, checksum types, and other capabilities using filters. (Reviewed by Cynthia Shang.)
2017-06-09 17:51:41 -04:00
David Steele
d68b48d19b Improved support for --require option and section depends now default to the previous section. 2017-02-11 10:26:54 -05:00
David Steele
c9b49b0d7e Doc engine improvements.
Bug Fixes:

* Fixed and issue that suppressed exceptions in PDF builds.

Features:

* Allow a source to be included as a section so large documents can be broken up.
* Added section link support to Markdown output.
* Added list support to PDF output.
* Added include option to explicitly build sources (complements the exclude option though both cannot be used in the same invocation).
* Added keyword-add option to add keywords without overriding the default keyword.
* Added debug option to doc.pl to easily add the debug keyword to documentation builds.
* Added pre option to doc.pl to easily add the pre keyword to documentation builds.

Refactoring:

* Improvements to markdown rendering.
* Remove code dependency on project variable, instead use title param.
2016-11-17 16:35:11 -05:00
David Steele
f43e5bc52d Removed extraneous use lib directives from Perl modules.
Suggested by Devrim Gündüz.
2016-11-04 13:56:26 +02:00
David Steele
41669a826e Added --dev option to doc.pl to easily add dev keyword to documentation builds. 2016-10-05 21:22:42 -04:00
David Steele
2a18674111 Added the log-level-stderr option.
Controls whether console log messages are sent to stderr or stdout. By default this is set to warn which represents a change in behavior from previous versions, even though it may be more intuitive. Setting log-level-stderr=off will preserve the old behavior.

Suggested by Sascha Biberhofer.
2016-10-05 09:09:30 -04:00
David Steele
dd8d781217 Safely check eval blocks and convert $@ to $EVAL_ERROR. 2016-09-06 09:44:50 -04:00
David Steele
6e52808065 Added release.pl to make releases reproducible. 2016-07-02 11:08:25 -04:00
David Steele
b571218930 Minor refactor of version variable to a constant.
It had originally been designed to play nice with a specific packaging tool but that tool was never used.
2016-06-26 20:53:45 -04:00
David Steele
c8f806a293 Major refactor of the test suite.
* Make the code more modular and object-oriented.
* Multiple Docker containers can now be created for a single test to simulate more realistic environments.
2016-06-24 08:12:58 -04:00
David Steele
eaa981c5aa Added execution cache for document generation.
Added an execution cache so that documentation can be generated without setting up the full container environment. This is useful for packaging, keeps the documentation consistent for a release, and speeds up generation when no changes are made in the execution list.
2016-06-02 09:32:56 -04:00
David Steele
df6086bd24 Added a man page to document generation. 2016-06-02 09:25:12 -04:00
Cynthia Shang
5a85122841 Moved change log to website.
The change log was the last piece of documentation to be rendered in Markdown only.  Wrote a converter so the document can be output by the standard renderers.  The change log will now be located on the website and has been renamed to "Releases".
2016-05-26 09:20:55 -04:00
David Steele
c604b6e657 Test release version using change-log.xml instead of CHANGELOG.md.
This is in preparation for moving the change log to the website and removing it from Github.
2016-05-23 19:33:02 -04:00
Cynthia Shang
28c5e54b09 Added SEO and sharing features to the website.
Descriptions wordsmithed (for better or worse) by committer.
2016-05-16 17:01:48 -04:00
Cynthia Shang
6cd1c42ddc Add usage documentation for test.pl. 2016-05-03 16:28:20 -04:00
David Steele
dee3e86ff8 README.md is now rendered by new Markdown code. 2016-04-16 11:55:23 -04:00
Cynthia Shang
9a7d8b26cc Fixed some inaccurate statements in the user guide.
Fixed typo in documentation code comments.
2016-04-14 13:50:58 -04:00
David Steele
18fd25233b New simpler configuration and consistent project/exe/path naming.
* The repo-path option now always refers to the repository where backups and archive are stored, whether local or remote, so the repo-remote-path option has been removed. The new spool-path option can be used to define a location for queueing WAL segments when archiving asynchronously. Otherwise, a local repository is no longer required.

* Implemented a new config format which should be far simpler to use. See the User Guide and Configuration Reference for details but for a simple configuration all options can now be placed in the stanza section. Options that are shared between stanzas can be placed in the [global] section. More complex configurations can still make use of command sections though this should be a rare use case.

* The default configuration filename is now pgbackrest.conf instead of pg_backrest.conf. This was done for consistency with other naming changes but also to prevent old config files from being loaded accidentally.

* The default repository name was changed from /var/lib/backup to /var/lib/pgbackrest.

* Lock files are now stored in /tmp/pgbackrest by default. These days /run/pgbackrest would be the preferred location but that would require init scripts which are not part of this release. The lock-path option can be used to configure the lock directory.

* Log files are now stored in /var/log/pgbackrest by default and no longer have the date appended so they can be managed with logrotate. The log-path option can be used to configure the lock directory.

* Executable filename changed from pg_backrest to pgbackrest.
2016-04-14 09:30:54 -04:00
John K. Harvey
1bbf3e6db4 Fixed #181: Missing semicolon violates code style. 2016-03-22 22:18:33 -04:00
David Steele
c8f863fbab Text execution improvements:
1) Tests for all operating systems can now be run with a single command.
2) Tests can be run in parallel with --process-max.
3) Container generation now integrated into test.pl
4) Some basic test documentation.
2016-01-09 08:21:53 -05:00
David Steele
b0a6954671 A number of doc improvements:
1) Started on a general markdown renderer
2) Internal links now work in PDF
3) Improvements to PDF styling
4) Some comment and formatting fixes
5) User guide edits.
2015-12-23 11:04:26 -05:00
David Steele
fa05715dec Added documentation in the user guide for delta restores, expiration, dedicated backup hosts, starting and stopping pgBackRest, and replication. 2015-11-22 16:44:01 -05:00
David Steele
57a06ba3b1 Implemented issue #148: Website with basic user guide. 2015-10-28 10:10:36 +01:00
David Steele
3dc0142244 Renamed userguide.xml to reference.xml so it doesn't conflict with the new user guide. 2015-10-08 14:36:39 -04:00
David Steele
ac3c0d43ab Implemented issue #132: Improved command-line help.
Implemented issue #133: Dynamic module loading where possible.
2015-09-08 07:31:24 -04:00
David Steele
ee55817fce Refactoring documentation generator. 2015-09-02 18:55:04 -04:00
David Steele
6a9377a0a9 Code cleanup and refactoring to standardize on patterns that have evolved over time. 2015-08-29 14:20:46 -04:00
David Steele
2edf5d4bf7 Split most of README.md out into CHANGELOG.md and USERGUIDE.md.
Added release dates to change log.
2015-08-07 14:43:53 -04:00
David Steele
bb443dd098 Renamed pg_backrest.pl to pg_backrest in the docs. 2015-07-06 17:59:44 -04:00
David Steele
38f48be3cf Improvements to help to make it more dynamic depending on environment.
Changed PgBackRest to pgBackRest.
2015-07-02 10:05:13 -04:00