Building documentation¶

Install dependencies for building documentation¶

OpenStack maintains a tool called bindep that maintains a list of dependencies for Linux package managers. When you run the tox -e bindep command, read the error messages and install the dependencies based on the error messages returned. Continue to run until your local environment meets the requirements as listed in bindep.txt in the repository.

• On MacOS

Open a Terminal window. Make sure you have Python installed. Many contributors use the Homebrew tool instructions.

$ brew install python
$ pip install tox

• On Ubuntu or Debian:

  # apt-get install python-pip
  # pip install tox
  $ tox -e bindep
  # apt-get install <indicated missing package names>
  

• On RHEL or CentOS including Fedora:

  # yum install python-pip
  # pip install tox
  $ tox -e bindep
  # yum install <indicated missing package names>
  

• On openSUSE or SUSE Linux Enterprise:

  # zypper in python-pip
  # pip install tox
  $ tox -e bindep
  # zypper in <indicated missing package names>
  

• On Windows

To the doc build scripts as-is on Windows, first install Git for Windows. Make sure you have a working Python environment, and then use Git Bash to run all tox commands within the repository directory:

$ pip install tox

Build workflow¶

Once Tox is installed and configured, execute tox -e <jobname> to run a particular job:

• To build all docs, open your local openstack-manuals project and run:

  $ tox -e checkbuild
  

• To build a specific guide, add the guide folder name to the tox -e build command. For example:

  $ tox -e build -- contributor-guide
  

  Note

  This command does not work for the install-guide, as it contains conditional content. To build specific parts of the Installation tutorials, use the commands below:

  $ tox -e install-guide-debconf
  $ tox -e install-guide-debian
  $ tox -e install-guide-obs
  $ tox -e install-guide-rdo
  $ tox -e install-guide-ubuntu
  

This runs the sphinx-build command. When the build is finished, it displays in the openstack-manuals/publish-docs directory. You can open the .html file in a browser to view the resulting output.

If you do not want to use Tox, install the below prerequisites locally:

# pip install sphinx
# pip install openstackdocstheme
# pip install sphinxmark

To get the .html output locally, switch to the directory containing a conf.py and run:

$ sphinx-build /path/to/source/ path/to/build/

The RST source is built into HTML using Sphinx, so that it is displayed on the docs.openstack.org/<guide-name>. For example: https://docs.openstack.org/user-guide/.

Using Tox to check builds¶

As a part of the review process, the OpenStack CI system runs scripts to check that the patch is fine. Locally, you can use the Tox tool to ensure that a patch works. To check all books, run the following command from the base directory of repository:

$ tox

The following individual checks are also available:

• tox -e checkniceness - to run the niceness tests (for example, to see extra whitespaces)
• tox -e checksyntax - to run syntax checks
• tox -e checklang - to check all the translated manuals
• tox -e docs - to build only RST-sourced manuals
• tox -e checkbuild - to build all the manuals. This will also generate a directory publish-docs that contains the built files for inspection.

Generate PDF¶

To build a specific guide with a PDF file, use the tox build command for the guide with the pdf option. For example:

$ tox -e build -- contributor-guide --pdf

PDF builds are accomplished using LaTeX as an intermediate format. Currently, you can generate a PDF file for a limited number of guides. The supported list is maintained in the tools/build-all-rst.sh file.

Build an existing patch locally¶

To build a patch locally:

1. Change to the directory containing the appropriate repository:

   • openstack-manuals
   • security-doc
   • api-site

   For example:

   $ cd openstack-manuals
   

2. Create a local branch that contains the particular patch.

   $ git review -d PATCH_ID
   

   Where the value of PATCH_ID is a Gerrit commit number. You can find this number on the patch link, https://review.openstack.org/#/c/PATCH_ID.

3. Build all the books that are affected by changes in the patch set:

   $ tox -e checkbuild
   

4. Find the build result in publish-docs/index.html.

Checklang job¶

We only gate on manual/language combinations that are translated sufficiently. For example, in openstack-manuals this includes Japanese with the Security Guide, HA Guide and Install Guides.

• If an import from Zanata fails, we do not approve the import.
• If any other patch fails, the failure might get ignored.
• In any case of failure, a bug gets reported against the i18n project.

If you want to manually run this check on your local workstation you can use the checklang environment (tox -e checklang). To use this environment, you first have to install the xml2po utility on your local workstation. xml2po is part of the gnome-doc-utils and can be installed with yum install gnome-doc-utils (on RedHat-based distributions), or zypper install xml2po (on SUSE-based distributions).