Although you can use Linux, MacOS, or Windows to build locally the Sphinx
documentation for OpenStack, Linux is the preferred build environment as it
offers the most complete support for documentation building.

OpenStack project and documentation repositories use a tox.ini file with
specific sections that run jobs using the Tox tool, a virtualenv-based
automation of test activities.

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.

Important

Ensure you run bindep in each individual project repository that you
clone if you want to build the documentation.

Running these commands will install all required packages for building both
RST and PDF files. If you do not build PDF files, you do not need to
install the texlive packages and
Liberation font family.

You cannot run tox -e bindep on Mac OS X as it uses a Linux tool
to parse the information. Issue logged here.

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:

Once Tox is installed and configured, execute tox -e <jobname>
to run a particular job. For example, to build all guides in
openstack-manuals, run the following command:

$ tox -e docs

The individual Tox jobs you can run are explained in detail in the
README file
in the repository.

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 guides, run the tox command
from the base directory of repository.

The build jobs for documentation are stored in the
project-config
repository. The build jobs build to the docs.openstack.org and
developer.openstack.org sites, copying built files via FTP.

The release-specific guides are built for the currently supported branches
(current and previous releases), development happens on the master branch.
The continuously released guides are only built on the master branch.

Like other projects, the documentation projects use a number of jobs
that do automatic testing of patches.

Look for the release name you want to build, such as Essex, and check out
the corresponding tag:

$ git checkout essex-eol

Git checks out the files and when complete, shows you the reference point
for your local files, such as, HEADisnowate6b9f61...fixdelay_auth_decisionparameter.

Read the README.rst file available at that point in time for the
prerequisites for building the documentation locally. For example, you may
need to install Apache Maven in order to build old documents.