From 28dbce9a87fd54e6d99f34288f4b2c4977eccd29 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 5 Jul 2018 16:33:11 -0400 Subject: [PATCH] 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 --- reference/project-testing-interface.rst | 27 +++++++++++++++++++------ reference/pti/python.rst | 16 --------------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/reference/project-testing-interface.rst b/reference/project-testing-interface.rst index 057608f48..75fe1ebc8 100644 --- a/reference/project-testing-interface.rst +++ b/reference/project-testing-interface.rst @@ -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 ------------- diff --git a/reference/pti/python.rst b/reference/pti/python.rst index 6ba2b53b4..47fb6e038 100644 --- a/reference/pti/python.rst +++ b/reference/pti/python.rst @@ -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 -------------