pgbackrest/doc/xml/documentation.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 different platforms: <id>centos7</id>, <id>centos8</id> and <id>debian</id>. This will build the HTML user guide for CentOS/RHEL 7:</p>

        <code-block type="bash">
./doc.pl --out=html --include=user-guide --var=os-type=centos7
        </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=centos8 --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. For <id>centos7</id>/<id>centos8</id> these defaults are generally fine, but for <id>debian</id> it can 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
        </code-block>

        <p>The following is a sample CentOS/RHEL 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>CentOS/RHEL 7:</p>

        <code-block type="bash">
./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
        </code-block>

        <p>CentOS/RHEL 8:</p>

        <code-block type="bash">
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=centos8 --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>