Merge "update the pti to use tox for building docs"

This commit is contained in:
Zuul 2018-07-16 13:41:30 +00:00 committed by Gerrit Code Review
commit ab91f899d7
2 changed files with 21 additions and 22 deletions

View File

@ -55,17 +55,32 @@ To support documentation generation, projects should:
``doc`` tag.
* Depend on ``openstackdocstheme`` for documentation and configure it to be
used in ``doc/source/conf.py``.
* Have a ``docs`` environment set up in a ``tox.ini`` file within the
repository.
Assuming requirements have been properly installed as indicated by
``doc/requirements.txt`` and ``bindep.txt``, the following command should
work with no additional setup and should result in the documentation being
emitted into ``doc/build/html``.
Assuming non-Python requirements have been properly installed as
indicated by ``bindep.txt``, the following command should work with no
additional setup and should result in the documentation being emitted
into ``doc/build/html``.
.. code-block:: bash
sphinx-build -b html doc/source doc/build/html
tox -e docs
Language specific instructions supplement these and are in addition to them.
.. note::
We strongly discourage project teams from adding commands to the
``docs`` environment beyond:
.. code-block:: bash
sphinx-build -W -b html doc/source doc/build/html
Additional logic needed around Sphinx generation should go into
Sphinx plugins.
Language specific instructions supplement these and are in addition to
them.
Release Notes
-------------

View File

@ -148,22 +148,6 @@ dir should be the $project.pot file. For instance, for nova, there should be
nova/locale/nova.pot. Babel commands should be configured out output their .mo
files in to $project/locale as well.
Documentation
-------------
In addition to the normal PTI :ref:`pti-documentation` requirements, as a
convenience for developers, it is recommended that projects provide
a ``docs`` environment for tox that will run
.. code-block:: bash
sphinx-build -b html doc/source doc/build
The project infrastructure will not use ``tox -e docs`` to build the
documentation. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the command section of that tox environment. Additional
logic needed around Sphinx generation should go into Sphinx plugins.
Release Notes
-------------