mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2025-01-18 04:58:51 +02:00
ccac75e7de
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.
114 lines
4.5 KiB
XML
114 lines
4.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE doc SYSTEM "doc.dtd">
|
|
<doc title="{[project]}" subtitle="Building Documentation" toc="y">
|
|
<description>Building {[project]} Documentation</description>
|
|
|
|
<section id="general">
|
|
<title>General Builds</title>
|
|
|
|
<p>The <backrest/> documentation can output a variety of formats and target several platforms and <postgres/> versions.</p>
|
|
|
|
<p>This will build all documentation with defaults:</p>
|
|
|
|
<code-block type="bash">
|
|
./doc.pl
|
|
</code-block>
|
|
|
|
<p>The user guide can be built for <id>rhel</id> and <id>debian</id>. This will build the HTML user guide for RHEL/CentOS:</p>
|
|
|
|
<code-block type="bash">
|
|
./doc.pl --out=html --include=user-guide --var=os-type=rhel
|
|
</code-block>
|
|
|
|
<p>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:</p>
|
|
|
|
<code-block type="bash">
|
|
./doc.pl --out=html --include=user-guide --var=os-type=rhel --no-cache
|
|
</code-block>
|
|
|
|
<p>Each <id>os-type</id> has a default container image that will be used as a base for creating hosts but it may be useful to change the image.</p>
|
|
|
|
<code-block type="bash">
|
|
./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9
|
|
./doc.pl --out=html --include=user-guide --var=os-type=rhel --var=os-image=centos:7
|
|
</code-block>
|
|
|
|
<p>The following is a sample RHEL/CentOS 7 configuration that can be used for building the documentation.</p>
|
|
|
|
<code-block type="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
|
|
|
|
# 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
|
|
</code-block>
|
|
</section>
|
|
|
|
<section id="package">
|
|
<title>Building with Packages</title>
|
|
|
|
<p>A user-specified package can be used when building the documentation. Since the documentation exercises most <backrest/> functionality this is a great way to smoke-test packages.</p>
|
|
|
|
<p>The package must be located within the <backrest/> repo and the specified path should be relative to the repository base. <path>test/package</path> is a good default path to use.</p>
|
|
|
|
<p>Ubuntu 16.04:</p>
|
|
|
|
<code-block type="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
|
|
</code-block>
|
|
|
|
<p>RHEL/CentOS 7:</p>
|
|
|
|
<code-block type="bash">
|
|
./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
|
|
</code-block>
|
|
|
|
<p>RHEL/CentOS 8:</p>
|
|
|
|
<code-block type="bash">
|
|
./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
|
|
</code-block>
|
|
|
|
<p>Packages can be built with <file>test.pl</file> using the following configuration on top of the configuration given for building the documentation.</p>
|
|
|
|
<code-block type="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
|
|
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
|
|
</code-block>
|
|
</section>
|
|
</doc>
|