Merge "update the pti to use tox for building docs"
This commit is contained in:
commit
ab91f899d7
|
@ -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
|
||||
-------------
|
||||
|
|
|
@ -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
|
||||
-------------
|
||||
|
||||
|
|
Loading…
Reference in New Issue