openstack/governance
Code Issues Proposed changes

Update docs job info to match current PTI

Browse Source 
Our doc requirements have been updated to run documentation builds
using sphinx-build instead of calling tox. The PTI reference for
Python code still contained old recommendations to use
[build_sphinx] in setup.cfg. This updates this Python recommendation
to match what is stated in the full PTI with additions for making
local runs easier through using tox.

Change-Id: Ibdaeefdac6b6bbeef544778d2fa5c3972d180cb8
This commit is contained in:
Sean McGinnis
2018-03-26 10:54:06 -05:00
parent 0fd9d1062d
commit 9ecbfde532
1 changed files with 9 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
reference/pti/python.rst
View File

@@ -20,14 +20,15 @@ Projects which are compatible with Python 3 must also be able to do:
Specific commands Specific commands
----------------- -----------------
To drive the above tasks, the following commands should be supported in a clean tree: To drive the above tasks, the following commands should be supported in a clean
tree:
- tox -epy27 - tox -epy27
- tox -epep8 - tox -epep8
- tox -ecover - tox -ecover
- python setup.py sdist - python setup.py sdist
- python setup.py bdist_wheel - python setup.py bdist_wheel
- tox -evenv python setup.py build_sphinx - sphinx-build -b html doc/source doc/build
Projects that are translated should also support: Projects that are translated should also support:
@@ -150,25 +151,15 @@ files in to $project/locale as well.
Documentation Documentation
------------- -------------
In addition to the normal PTI :ref:`pti-documentation` requirements, Python In addition to the normal PTI :ref:`pti-documentation` requirements, as a
projects should put the following into their setup.cfg so that convenience for developers, it is recommended that projects provide
``python setup.py build_sphinx`` continues to work: a ``docs`` environment for tox that will run
:: .. code-block:: bash
[build_sphinx] sphinx-build -b html doc/source doc/build
source-dir = doc/source
build-dir = doc/build
It may be assumed that the project will be installed before Sphinx is run The project infrastructure will not use ``tox -e docs`` to build the
using ``pip install .``.
As a convenience for developers, it is recommended that projects provide
a ``docs`` environment for tox that will run either
``sphinx-build -b html doc/source doc/build`` or
``python setup.py build_sphinx``.
The project infrastructure will not use ``tox -edocs`` to build the
documentation. Therefore it is **STRONGLY** discouraged for people to put documentation. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the command section of that tox environment. Additional additional logic into the command section of that tox environment. Additional
logic needed around Sphinx generation should go into Sphinx plugins. logic needed around Sphinx generation should go into Sphinx plugins.