1
0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-12 10:04:14 +02:00
pgbackrest/doc
David Steele 117f03eba1 Prepare configuration module for multi-repository support.
Refactor the code to allow a dynamic number of indexes for indexed options, e.g. pg-path. Our reliance on getopt_long() still limits the number of indexes we can have per group, but once this limitation is removed the rest of the code should be happy with dynamic numbers of indexes (with a reasonable maximum).

Add an option to set a default in each group. This was previously handled by the host-id option but now there is a specific option for each group, pg and repo. These remain internal until they can be fully tested with multi-repo support. They are fully tested for internal usage.

Remove the ConfigDefineOption enum and use the ConfigOption enum instead. They are now equal since the indexed options (e.g. cfgOptRepoHost2) have been removed from ConfigOption.

Remove the config/config test module and add required tests to the config/parse test module. Parsing is now the only way to load a config so this removes some redundancy.

Split new internal config structures and functions into a new header file, config.intern.h. More functions will need to be moved over from config.h but that will need to be done in a future commit to reduce churn.

Add repoIdx to repoIsLocal() and storageRepo*(). Multi-repository support requires that repo locality and storage be accessible by index. This allows, for example, multiple repos to be iterated in a loop. This could be done in a separate commit but doesn't seem worth it since the code is related.

Remove the type parameter from storageRepoGet(). This parameter existed solely to provide coverage for the case where the storage type was invalid. A better pattern is to check that the type is S3 once all other types have been ruled out.
2020-11-23 15:55:46 -05:00
..
example JSON output from the info command is no longer pretty-printed. 2019-10-11 12:56:03 -04:00
lib/pgBackRestDoc Add text rendering for page links missed in 597739fa. 2020-10-05 08:37:48 -04:00
resource Spell out three exclamation points in git-history.cache. 2020-10-28 08:59:43 -04:00
xml Prepare configuration module for multi-repository support. 2020-11-23 15:55:46 -05:00
.gitignore Updated vagrant to new version and image. 2017-03-14 22:05:17 -04:00
doc.pl Move pgBackRest::Version module to pgBackRestDoc::ProjectInfo. 2020-03-10 17:57:02 -04:00
FORMAT.md Add notes about optional symlinks to repo format 6 design. 2020-09-01 11:02:44 -04:00
manifest.xml Remove XML source for test/README.md. 2020-04-20 16:21:53 -04:00
README.md Add openssl-devel install to documentation build in 711b3e67. 2019-01-30 22:02:42 +02:00
RELEASE.md v2.30: PostgreSQL 13 Support 2020-10-05 11:51:45 -04:00
release.pl v2.28: Azure Repository Storage 2020-07-20 08:57:22 -04:00

pgBackRest
Building Documentation

General Builds

The pgBackRest documentation can output a variety of formats and target several platforms and PostgreSQL versions.

This will build all documentation with defaults:

./doc.pl

The user guide can be built for different platforms: centos6, centos7, and debian. This will build the HTML user guide for CentOS/RHEL 7:

./doc.pl --out=html --include=user-guide --var=os-type=centos7

Documentation generation will build a cache of all executed statements and use the cache to build the documentation quickly if no executed statements have changed. This makes proofing text-only edits very fast, but sometimes it is useful to do a full build without using the cache:

./doc.pl --out=html --include=user-guide --var=os-type=centos6 --no-cache

Each os-type has a default container image that will be used as a base for creating hosts. For centos6/centos7 these defaults are generally fine, but for debian it can be useful to change the image.

./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9

The following is a sample CentOS/RHEL 7 configuration that can be used for building the documentation.

# Install docker
sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce
sudo systemctl start docker

# Install tools
sudo yum install -y git wget

# Install latex (for building PDF)
sudo yum install -y texlive texlive-titlesec texlive-sectsty texlive-framed texlive-epstopdf ghostscript

# Install Perl modules that do not have CentOS packages via CPAN
sudo yum install -y yum cpanminus
sudo yum groupinstall -y "Development Tools" "Development Libraries"
sudo cpanm install --force XML::Checker::Parser

# Add documentation test user
sudo groupadd test
sudo adduser -gtest -n testdoc
sudo usermod -aG docker testdoc

Building with Packages

A user-specified package can be used when building the documentation. Since the documentation exercises most pgBackRest functionality this is a great way to smoke-test packages.

The package must be located within the pgBackRest repo and the specified path should be relative to the repository base. test/package is a good default path to use.

Ubuntu 16.04:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=debian --var=os-image=ubuntu:16.04 --var=package=test/package/pgbackrest_2.08-0_amd64.deb

CentOS/RHEL 6:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=centos6 --var=package=test/package/pgbackrest-2.08-1.el6.x86_64.rpm

CentOS/RHEL 7:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=centos7 --var=package=test/package/pgbackrest-2.08-1.el7.x86_64.rpm

Packages can be built with test.pl using the following configuration on top of the configuration given for building the documentation.

# Install recent git
sudo yum remove -y git
sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm
sudo yum install -y git2u-all

# Install Perl modules
sudo yum install -y perl-ExtUtils-ParseXS perl-ExtUtils-Embed perl-ExtUtils-MakeMaker perl-YAML-LibYAML

# Install dev libraries
sudo yum install -y libxml2-devel openssl-devel

# Add test user with sudo privileges
sudo adduser -gtest -n test
sudo usermod -aG docker test
sudo chmod 750 /home/test

sudo echo 'test ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pgbackrest

# Add pgbackrest user required by tests
sudo adduser -gtest -n pgbackrest