db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-14 10:13:05 +02:00
Code Issues Releases Activity
1141dc2070
pgbackrest/doc/README.md

90 lines
3.5 KiB
Markdown
Raw Normal View History

Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
# pgBackRest <br/> 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:
```bash
./doc.pl
```
Use Rocky Linux for documentation builds instead of CentOS. Since CentOS 8 will be EOL at the end of the year it makes sense to do this now. The centos:8 image is still used in documentation.xml because changes there require manual testing, which will need to be done at a later date. The changes are not user-facing, however, and can be done at any time. Also update CentOS references to RHEL since that is what we are emulating for testing purposes.
2021-10-28 21:15:49 +02:00
The user guide can be built for `rhel` and `debian`. This will build the HTML user guide for RHEL:
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```bash
Consolidate RHEL/CentOS user guide into a single document. The user guide was split primarily to provide documentation for the stop-auto option in PostgreSQL <= 9.5. Now that 9.5 is EOL there does not seem to be a good reason to generate an extra user guide. The stop-auto function is still documented in the reference. Leave the stop-auto documentation in the user guide in case we want to manually generate documentation for older versions. Also rename centos to rhel for most identifiers since that is the core platform we are building for, similar to how we label 'debian' builds even though we generally use Ubuntu. With CentOS set to become an upstream for RHEL later this year, we'll likely need to pick a new test distribution, perhaps Rocky Linux if that gets off the ground.
2021-05-24 22:03:15 +02:00
./doc.pl --out=html --include=user-guide --var=os-type=rhel
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```
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:
```bash
Consolidate RHEL/CentOS user guide into a single document. The user guide was split primarily to provide documentation for the stop-auto option in PostgreSQL <= 9.5. Now that 9.5 is EOL there does not seem to be a good reason to generate an extra user guide. The stop-auto function is still documented in the reference. Leave the stop-auto documentation in the user guide in case we want to manually generate documentation for older versions. Also rename centos to rhel for most identifiers since that is the core platform we are building for, similar to how we label 'debian' builds even though we generally use Ubuntu. With CentOS set to become an upstream for RHEL later this year, we'll likely need to pick a new test distribution, perhaps Rocky Linux if that gets off the ground.
2021-05-24 22:03:15 +02:00
./doc.pl --out=html --include=user-guide --var=os-type=rhel --no-cache
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```
Consolidate RHEL/CentOS user guide into a single document. The user guide was split primarily to provide documentation for the stop-auto option in PostgreSQL <= 9.5. Now that 9.5 is EOL there does not seem to be a good reason to generate an extra user guide. The stop-auto function is still documented in the reference. Leave the stop-auto documentation in the user guide in case we want to manually generate documentation for older versions. Also rename centos to rhel for most identifiers since that is the core platform we are building for, similar to how we label 'debian' builds even though we generally use Ubuntu. With CentOS set to become an upstream for RHEL later this year, we'll likely need to pick a new test distribution, perhaps Rocky Linux if that gets off the ground.
2021-05-24 22:03:15 +02:00
Each `os-type` has a default container image that will be used as a base for creating hosts but it may be useful to change the image.
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```bash
./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9
Consolidate RHEL/CentOS user guide into a single document. The user guide was split primarily to provide documentation for the stop-auto option in PostgreSQL <= 9.5. Now that 9.5 is EOL there does not seem to be a good reason to generate an extra user guide. The stop-auto function is still documented in the reference. Leave the stop-auto documentation in the user guide in case we want to manually generate documentation for older versions. Also rename centos to rhel for most identifiers since that is the core platform we are building for, similar to how we label 'debian' builds even though we generally use Ubuntu. With CentOS set to become an upstream for RHEL later this year, we'll likely need to pick a new test distribution, perhaps Rocky Linux if that gets off the ground.
2021-05-24 22:03:15 +02:00
./doc.pl --out=html --include=user-guide --var=os-type=rhel --var=os-image=centos:7
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```
Use Rocky Linux for documentation builds instead of CentOS. Since CentOS 8 will be EOL at the end of the year it makes sense to do this now. The centos:8 image is still used in documentation.xml because changes there require manual testing, which will need to be done at a later date. The changes are not user-facing, however, and can be done at any time. Also update CentOS references to RHEL since that is what we are emulating for testing purposes.
2021-10-28 21:15:49 +02:00
The following is a sample RHEL 7 configuration that can be used for building the documentation.
Add examples for building a documentation host.
2019-01-30 16:53:59 +02:00
```bash
# 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
Add latex install to documentation build in 711b3e67.
2019-01-30 21:11:52 +02:00
# Install latex (for building PDF)
sudo yum install -y texlive texlive-titlesec texlive-sectsty texlive-framed texlive-epstopdf ghostscript
Use Rocky Linux for documentation builds instead of CentOS. Since CentOS 8 will be EOL at the end of the year it makes sense to do this now. The centos:8 image is still used in documentation.xml because changes there require manual testing, which will need to be done at a later date. The changes are not user-facing, however, and can be done at any time. Also update CentOS references to RHEL since that is what we are emulating for testing purposes.
2021-10-28 21:15:49 +02:00
# Install Perl modules via CPAN that do not have packages
Add examples for building a documentation host.
2019-01-30 16:53:59 +02:00
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
```
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
## 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:
```bash
./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
```
Use Rocky Linux for documentation builds instead of CentOS. Since CentOS 8 will be EOL at the end of the year it makes sense to do this now. The centos:8 image is still used in documentation.xml because changes there require manual testing, which will need to be done at a later date. The changes are not user-facing, however, and can be done at any time. Also update CentOS references to RHEL since that is what we are emulating for testing purposes.
2021-10-28 21:15:49 +02:00
RHEL 7:
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```bash
Remove double spaces from comments and documentation. Double spaces have fallen out of favor in recent years because they no longer contribute to readability. We have been using single spaces and editing related paragraphs for some time, but now it seems best to update the remaining instances to avoid churn in unrelated commits and to make it clearer what spacing contributors should use.
2023-05-02 11:57:12 +02:00
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=rhel --var=os-image=centos:7 --var=package=test/package/pgbackrest-2.08-1.el7.x86_64.rpm
Add documentation for building the documentation. A basic primer for building the documentation. Lots that could be added, but it's a start.
2018-12-12 20:52:23 +02:00
```
Use Rocky Linux for documentation builds instead of CentOS. Since CentOS 8 will be EOL at the end of the year it makes sense to do this now. The centos:8 image is still used in documentation.xml because changes there require manual testing, which will need to be done at a later date. The changes are not user-facing, however, and can be done at any time. Also update CentOS references to RHEL since that is what we are emulating for testing purposes.
2021-10-28 21:15:49 +02:00
RHEL 8:
Add RHEL/CentOS 8 documentation. Update RHEL/CentOS 7 to cover the versions that were previously covered by RHEL/CentOS 6. Since RHEL/CentOS 7/8 work the same update the documentation logic and labels to reflect this compatibility.
2020-12-04 17:59:57 +02:00
```bash
Consolidate RHEL/CentOS user guide into a single document. The user guide was split primarily to provide documentation for the stop-auto option in PostgreSQL <= 9.5. Now that 9.5 is EOL there does not seem to be a good reason to generate an extra user guide. The stop-auto function is still documented in the reference. Leave the stop-auto documentation in the user guide in case we want to manually generate documentation for older versions. Also rename centos to rhel for most identifiers since that is the core platform we are building for, similar to how we label 'debian' builds even though we generally use Ubuntu. With CentOS set to become an upstream for RHEL later this year, we'll likely need to pick a new test distribution, perhaps Rocky Linux if that gets off the ground.
2021-05-24 22:03:15 +02:00
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=rhel --var=os-image=centos:8 --var=package=test/package/pgbackrest-2.08-1.el8.x86_64.rpm
Add RHEL/CentOS 8 documentation. Update RHEL/CentOS 7 to cover the versions that were previously covered by RHEL/CentOS 6. Since RHEL/CentOS 7/8 work the same update the documentation logic and labels to reflect this compatibility.
2020-12-04 17:59:57 +02:00
```
Add examples for building a documentation host.
2019-01-30 16:53:59 +02:00
Packages can be built with `test.pl` using the following configuration on top of the configuration given for building the documentation.
```bash
# 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
Add openssl-devel install to documentation build in 711b3e67.
2019-01-30 22:02:42 +02:00
sudo yum install -y libxml2-devel openssl-devel
Add examples for building a documentation host.
2019-01-30 16:53:59 +02:00
# 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
```
Reference in New Issue Copy Permalink