db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-01-18 04:58:51 +02:00
Code Issues Releases Activity

Add documentation for building the documentation.

Browse Source 
A basic primer for building the documentation.  Lots that could be added, but it's a start.
This commit is contained in:
David Steele 2018-12-12 13:52:23 -05:00
parent fdc76742c8
commit df947cfcb2
4 changed files with 109 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/README.md Normal file
View File

@ -0,0 +1,41 @@
# 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
```
The user guide can be built for different platforms: `centos6`, `centos7`, and `debian`. This will build the HTML user guide for CentOS/RHEL 7:
```bash
./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:
```bash
./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.
```bash
./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9
```
## 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
```
CentOS/RHEL 6:
```bash
./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:
```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
```

2
doc/manifest.xml
View File

@ -85,6 +85,7 @@
<source key="reference" type="custom"/>
<source key="release" type="custom"/>
<source key="coding"/>
<source key="documentation"/>
<source key="test"/>
</source-list>
@ -105,6 +106,7 @@
<render-source key="index" file="../../../README.md"/>
<render-source key="coding" file="../../../CODING.md"/>
<render-source key="test" file="../../../test/README.md"/>
<render-source key="documentation" file="../../README.md"/>
</render>
</render-list>
</doc>

62
doc/xml/documentation.xml Normal file
View File

@ -0,0 +1,62 @@
<?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>centos6</id>, <id>centos7</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=centos6 --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>centos6</id>/<id>centos7</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>
</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 6:</p>
<code-block type="bash">
./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
</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>
</section>
</doc>

4
doc/xml/release.xml
View File

@ -203,6 +203,10 @@
<p>Clarify that region/endpoint must be configured correctly for the bucket.</p>
</release-item>
<release-item>
<p>Add documentation for building the documentation.</p>
</release-item>
</release-improvement-list>
<release-development-list>