openstack-manuals/doc/contributor-guide/source/build-locally.rst

Building output locally

The openstack-manuals project uses a tox.ini file with specific sections that run jobs using the Tox tool, a virtualenv-based automation of test activities.

Tox prerequisites and installation

Install the prerequisites for Tox:

• On Ubuntu or Debian:

  # apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
    zlib1g-dev

  You may need to use pip install for some packages.

• On RHEL or CentOS including Fedora:

  # yum install gcc python-devel libxml2-devel libxslt-devel

• On openSUSE or SUSE Linux Enterprise:

  # zypper install gcc python-devel libxml2-devel libxslt-devel

Install python-tox:

# pip install tox

Build workflow

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

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

  tox -e checkbuild

• To build RST docs, run:

  tox -e docs

• 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 guide, use the commands below:

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

This runs the sphinx-build command. When the build is finished, it will be displayed 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

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, http://docs.openstack.org/user-guide-admin.

The DocBook source is built into HTML (webhelp) and PDF using XSLT transforms included to the DocBook project.

You can find tips how to troubleshoot the build at: Documentation/Troubleshooting.

Build DocBook locally without a Python environment

Maven plug-in must be installed to build the documentation. Run one of the below commands to install Maven:

• On Ubuntu or Debian:

  apt-get install maven

• On Fedora:

  yum install maven

• On openSUSE:

  zypper install maven

To build a specific DocBook guide, look for a pom.xml file within a subdirectory, switch to that directory, then run the mvn command using Maven plug-in in that directory. For example:

cd openstack-manuals/doc/image-guide
mvn clean generate-sources

Find the generated documentation in the openstack-manuals/doc/<guide-name>/target directory of the guide that you build. For example:

• PDF: openstack-manuals/doc/image-guide/target/docbkx/webhelp/ image-guide/image-guide.pdf
• HTML: openstack-manuals/doc/image-guide/target/docbkx/webhelp/ image-guide/content/index.html.

Using Tox to check builds

As a part of the review process, Jenkins runs gating 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 checkdeletions - to check that no deleted files are referenced
• tox -e checklinks - to check whether all the links work
• 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.

Note

• The scripts are not written for Windows, but we encourage cross-platform work on our scripts.
• If Tox stops working, try tox --recreate to rebuild the environment.