Follow the new PTI for document build

For compliance with the Project Testing Interface as described in:
[1] https://governance.openstack.org/tc/reference/project-testing-interface.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

[doc/requirements.txt] & [test-requirements.txt]
To support documentation generation in new PTI, project should have
list python dependencies needed for documentation in
doc/requirements.txt which are move from test-requirements.txt

[doc/source/contributor/index.rst] & [setup.cfg]
- Remove [pbr] section in setup.cfg [3], and unrelated lines in
contributor/index.rst
[3] http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html
- Add sphinxcontrib.apidoc to replace pbr autodoc

[tox.ini]
--ignore D000: pep8 require sphinx (which move to doc/requirements.txt)
to test doc/source files, however, docs already test the doc/source.
Therefore we can ignore the D000 error code.

Depends-On: https://review.openstack.org/#/c/559327/
Change-Id: Iee90f19a5e46978a97035eab7e4b1e0ec68b8684

doc/requirements.txt

@@ -0,0 +1,7 @@
+openstackdocstheme>=1.18.1 # Apache-2.0
+os-api-ref>=1.4.0 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
+sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
+sphinxcontrib-seqdiag>=0.8.4 # BSD

doc/source/conf.py

@@ -24,12 +24,12 @@ except TypeError:
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.viewcode',
+extensions = ['sphinx.ext.viewcode',
               'sphinx.ext.graphviz',
               'sphinxcontrib.httpdomain',
               'sphinxcontrib.pecanwsme.rest',
               'sphinxcontrib.seqdiag',
+              'sphinxcontrib.apidoc',
               'wsmeext.sphinxext',
               'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
@@ -43,6 +43,15 @@ try:
 except ImportError:
     openstackdocstheme = None
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../ironic'
+apidoc_output_dir = 'contributor/api'
+apidoc_excluded_paths = [
+    'db/sqlalchemy/alembic/env'
+    'db/sqlalchemy/alembic/versions/*',
+    'drivers/modules/ansible/playbooks*']
+apidoc_separate_modules = True
+
 repository_name = 'openstack/ironic'
 bug_project = 'ironic'
 bug_tag = ''

doc/source/contributor/index.rst

@@ -91,10 +91,7 @@ booting from Cinder volumes with VMs.
 Full Ironic Server Python API Reference
 ---------------------------------------
 
-* :ref:`modindex`
-
-.. # api/autoindex is hidden since it's in the modindex link above.
 .. toctree::
-  :hidden:
+  :maxdepth: 1
 
-  api/autoindex
+  api/modules

setup.cfg

@@ -189,20 +189,6 @@ ironic.hardware.types =
 ironic.database.migration_backend =
     sqlalchemy = ironic.db.sqlalchemy.migration
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-    ironic.db.sqlalchemy.alembic.env
-    ironic.db.sqlalchemy.alembic.versions.*
-    ironic.drivers.modules.ansible.playbooks*
-api_doc_dir = contributor/api
-
-[build_sphinx]
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
 [egg_info]
 tag_build =
 tag_date = 0

test-requirements.txt

@@ -18,11 +18,3 @@ testscenarios>=0.4 # Apache-2.0/BSD
 WebTest>=2.0.27 # MIT
 bashate>=0.5.1 # Apache-2.0
 flake8-import-order>=0.13 # LGPLv3
-
-# Doc requirements
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
-sphinxcontrib-seqdiag>=0.8.4 # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
-os-api-ref>=1.4.0 # Apache-2.0

tox.ini

@@ -35,7 +35,7 @@ commands =
   # the check and gate queues.
   {toxinidir}/tools/run_bashate.sh {toxinidir}
   # Check the *.rst files
-  doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001
+  doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001 --ignore D000
   # Check to make sure reno releasenotes created with 'reno new'
   {toxinidir}/tools/check-releasenotes.py
 
@@ -72,23 +72,27 @@ commands =
 commands = oslo_debug_helper -t ironic/tests/unit {posargs}
 
 [testenv:docs]
-# FIXME(dtantsur): workaround for bug #1714025
-basepython = python2
-setenv = PYTHONHASHSEED=0
-sitepackages = False
-envdir = {toxworkdir}/venv
-commands =
-  python setup.py build_sphinx
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:api-ref]
-# This environment is called from CI scripts to test and publish
-# the API Ref to developer.openstack.org.
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 whitelist_externals = bash
 commands =
   bash -c 'rm -rf api-ref/build'
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:releasenotes]
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands =
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html