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>
This 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
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
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
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
Sphinxmark uses the Pillow module for creating PNG files.
If you encounter
C module is not installed errors when Sphinx loads the
sphinxmark extension, you may need to install some of the
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/.
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:
The following individual checks are also availableː
publish-docsthat contains the built files for inspection.
To build a patch locally:
Change to the directory containing the appropriate repository:
$ cd openstack-manuals
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,
Build all the books that are affected by changes in the patch set:
$ tox -e checkbuild
Find the build result in
The build jobs for documentation are stored in the
zuul/layout.yaml file and the
file contain the Jenkins build jobs that build to the docs.openstack.org
and developer.openstack.org sites, copying built files via FTP.
The release specific books are built for the currently supported branches (current and previous releases), development happens on the master branch. The continuously released books are only built on the master branch.
Like other projects, the documentation projects use a number of jobs that do automatic testing of patches.
The current jobs are:
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 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).
OpenStack projects can follow different release models. The openstack-manuals repo follows two of these models, independent and cycle-with-milestones.
The docs repo, api-site, follows the independent release model.
The content that uses a stable branch method to indicate a point in time that content is set for a release (cycle-with-milestones) includes these docs:
When a release reaches an end-of-life status and is no longer maintained by the stable branch maintainers, the docs.openstack.org website redirects requests for old content to the latest release. Read more about support phases and stable branches in the Project Team Guide.
To build documentation from a particular release locally, follow these steps.
Clone a copy of the stable branch content locally, if you do not already have a local copy:
$ git clone git://git.openstack.org/openstack/openstack-manuals.git $ cd openstack-manuals
View the remote tags to see the tags for each release:
$ git tag -l 2012.1 2012.2 2013.1.rc1 2013.1.rc2 2013.2 diablo-eol essex-eol folsom-eol grizzly-eol havana-eol icehouse-eol juno-eol kilo-eol liberty-eol
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,
HEAD is now at e6b9f61... fix
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.