Follow the new PTI for document build

The Project Testing Interface [1] asks that we list requirements in
'doc/requirements.txt' and build docs by calling 'sphinx-build' directly
instead of via the 'build_sphinx' setuptool/distutils wrapper. Start
doing this.

[1] https://governance.openstack.org/tc/reference/project-testing-interface.html

Change-Id: If9342c8ea757b1735f2488db751008984fb33baf
This commit is contained in:
Stephen Finucane 2018-03-16 10:23:26 +00:00
parent 4f967e9ac0
commit 7b01024591
4 changed files with 23 additions and 21 deletions

11
doc/requirements.txt Normal file
View File

@ -0,0 +1,11 @@
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
sphinxcontrib-actdiag>=0.8.5 # BSD
sphinxcontrib-seqdiag>=0.8.4 # BSD
os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0
# releasenotes
reno>=2.5.0 # Apache-2.0
# redirect tests in docs
whereto>=0.3.0 # Apache-2.0

View File

@ -92,13 +92,6 @@ nova.scheduler.driver =
chance_scheduler = nova.scheduler.chance:ChanceScheduler
fake_scheduler = nova.tests.unit.scheduler.fakes:FakeScheduler
[build_sphinx]
builder = html man
all-files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[egg_info]
tag_build =
tag_date = 0

View File

@ -13,10 +13,6 @@ PyMySQL>=0.7.6 # MIT License
python-barbicanclient>=4.5.2 # Apache-2.0
python-ironicclient>=2.2.0 # Apache-2.0
requests-mock>=1.1.0 # Apache-2.0
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
sphinxcontrib-actdiag>=0.8.5 # BSD
sphinxcontrib-seqdiag>=0.8.4 # BSD
os-api-ref>=1.4.0 # Apache-2.0
oslotest>=3.2.0 # Apache-2.0
stestr>=1.0.0 # Apache-2.0
osprofiler>=1.4.0 # Apache-2.0
@ -24,17 +20,10 @@ testresources>=2.0.0 # Apache-2.0/BSD
testscenarios>=0.4 # Apache-2.0/BSD
testtools>=2.2.0 # MIT
bandit>=1.1.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0
gabbi>=1.35.0 # Apache-2.0
# vmwareapi driver specific dependencies
oslo.vmware>=2.17.0 # Apache-2.0
# releasenotes
reno>=2.5.0 # Apache-2.0
# placement functional tests
wsgi-intercept>=1.4.1 # MIT License
# redirect tests in docs
whereto>=0.3.0 # Apache-2.0

15
tox.ini
View File

@ -135,34 +135,41 @@ commands =
oslo_debug_helper {posargs}
[testenv:venv]
deps =
-r{toxinidir}/test-requirements.txt
-r{toxinidir}/doc/requirements.txt
commands = {posargs}
[testenv:docs]
# TODO(melwitt): This can be removed when the docs target can be run
# with python 3.x
basepython = python2.7
deps = -r{toxinidir}/doc/requirements.txt
commands =
rm -rf doc/source/api doc/build api-guide/build api-ref/build placement-api-ref/build
python setup.py build_sphinx
# Test the redirects
whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
# Check that all JSON files don't have \r\n in line.
bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'"
# Check that all included JSON files are valid JSON
bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
# Build docs
sphinx-build -W -b html doc/source doc/build/html
sphinx-build -W -b html api-guide/source api-guide/build/html
sphinx-build -W -b html api-ref/source api-ref/build/html
sphinx-build -W -b html placement-api-ref/source placement-api-ref/build/html
# Test the redirects. This must run after the main docs build
whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
[testenv:api-guide]
# This environment is called from CI scripts to test and publish
# the API Guide to developer.openstack.org.
deps = -r{toxinidir}/doc/requirements.txt
commands =
sphinx-build -W -b html -d api-guide/build/doctrees api-guide/source api-guide/build/html
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
deps = -r{toxinidir}/doc/requirements.txt
commands =
rm -rf api-ref/build
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
@ -170,6 +177,7 @@ commands =
[testenv:placement-api-ref]
# This environment is called from CI scripts to test and publish
# the Placement API Ref to developer.openstack.org.
deps = -r{toxinidir}/doc/requirements.txt
commands =
# Check that all placement api routes are in the documentation
python tools/placement_api_docs.py placement-api-ref/source/
@ -182,6 +190,7 @@ commands =
commands = bandit -r nova -x tests -n 5 -ll
[testenv:releasenotes]
deps = -r{toxinidir}/doc/requirements.txt
commands = bash -c tools/releasenotes_tox.sh
[flake8]