openstack
/
governance
Code Issues Proposed changes

update the pti to use tox for building docs 

As part of planning out the python3 transition we realized that in
order to have a self-testing patch in each repository to switch the
documentation build to use python3, we would need to include some
information in the repository that the job would read to decide which
version of python to use. After considering several options, we
realized that this requirement meant we had set the API for the
documentation jobs at the wrong "level" of the stack.

This patch restores the use of tox for building documentation in the
standard project testing interface. Rather than using the "venv"
environment, it specifies a new environment for "docs", based on the
common pattern we have in most projects to provide that as a
convenience for developers.

The Python-specific notes about adding the environment as a
convenience are removed, since it is now required.

Change-Id: Ibdee118f30972e9dc67952b921f493e9c1a116ff
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann 2018-07-05 16:33:11 -04:00
parent d2fb9b804b
commit 28dbce9a87
2 changed files with 21 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
reference/project-testing-interface.rst
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
-------------

16
reference/pti/python.rst
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
-------------