116 lines
3.1 KiB

Team and repository tags
.. image::
.. Change things from this point on
OpenStack Manuals
This repository contains documentation for the OpenStack project.
For more details, see the `OpenStack Documentation Contributor
Guide <>`_.
It includes these manuals:
* Administrator Guide
* Architecture Design Guide
* Command-Line Interface Reference
* Configuration Reference
* Documentation Contributor Guide
* End User Guide
* High Availability Guide
* Installation Tutorials
* Networking Guide
* Operations Guide
* Virtual Machine Image Guide
In addition to the guides, this repository contains:
* contents: ``www``
Various manuals are in subdirectories of the ``doc/`` directory.
Some pre-requisites are needed to build the guides. If you are using a Linux
operating system you can generate a report of missing local requirements with
the ``bindep`` command::
$ tox -e bindep
All guides are in the RST format. You can use ``tox`` to prepare
virtual environment and build all guides (HTML only):
$ tox -e docs
You can also build a specific guide.
For example, to build *OpenStack End User Guide*, use the following command::
$ tox -e build -- user-guide
You can find the root of the generated HTML documentation at::
To build a specific guide with a PDF file, add a ``-pdf`` option like::
$ tox -e build -- user-guide --pdf
The generated PDF file will be copied to the root directory of the
generated HTML documentation.
If you get this message `make: xelatex: No such file or directory` it means
your local environment does not have LaTeX installed. Read `Getting LaTeX
<>`_ for instructions.
Testing of changes and building of the manual
Install the Python tox package and run ``tox`` from the top-level
directory to use the same tests that are done as part of the OpenStack
CI jobs.
If you like to run individual tests, run:
* ``tox -e checkbuild`` - to actually build the manual
* ``tox -e checklang`` - to build translated manuals
* ``tox -e checkniceness`` - to run the niceness tests
* ``tox -e linkcheck`` - to run the tests for working remote URLs
The :command:`tox` command uses the openstack-doc-tools package to run the
Generated files
Some documentation files are generated using tools. These files include
a ``do not edit`` header and should not be modified by hand.
Please see `Generated files
Bugs should be filed on Launchpad, not GitHub:
Refer to to see where these documents are
published and to learn more about the OpenStack project.