Follow the new PTI for document build

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

Remove the '[build_sphinx]' and [pbr] sections as described in:
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Adds the use of sphinxcontrib.apidoc to get (mostly) the same output as what
was provided by the removed [pbr] section.

Change-Id: Ie7e3acef7161cb8f218c2333167490c8116a2122
Depends-On: https://review.openstack.org/#/c/560270/

doc/requirements.txt

@@ -0,0 +1,11 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+os-api-ref>=1.4.0 # Apache-2.0
+openstackdocstheme>=1.18.1 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0  # BSD
+
+# needed for apidoc support
+xattr>=0.9.2

doc/source/conf.py

@@ -48,11 +48,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['stevedore.sphinxext',
-              'sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
               'openstackdocstheme',
+              'sphinxcontrib.apidoc',
               ]
 
 # openstackdocstheme options
@@ -61,6 +61,16 @@
 bug_tag = ''
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../glance'
+apidoc_output_dir = 'contributor/api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'tests',
+    'db/sqlalchemy/*',
+    'db/sqlalchemy']
+apidoc_separate_modules = True
+
 config_generator_config_file = [
     ('../../etc/oslo-config-generator/glance-api.conf',
      '_static/glance-api'),

doc/source/contributor/index.rst

@@ -42,10 +42,8 @@ Developer Reference
    database_architecture
    domain_model
    domain_implementation
-.. toctree::
-   :maxdepth: 1
 
-   modules
+   Module Reference <api/modules>
 
 Development Roles
 -----------------

setup.cfg

@@ -79,12 +79,6 @@ glance.image_import.plugins =
 glance.image_import.internal_plugins =
     web_download = glance.async.flows._internal_plugins.web_download:get_flow
 
-[build_sphinx]
-builder = html man
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
 
 [egg_info]
 tag_build =
@@ -104,10 +98,3 @@ input_file = glance/locale/glance.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = glance/locale/glance.pot
-
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-  glance.tests.*
-  glance.db.sqlalchemy.*
-api_doc_dir = contributor/api

test-requirements.txt

@@ -32,8 +32,3 @@ pysendfile>=2.0.0 # MIT
 qpid-python>=0.26;python_version=='2.7' # Apache-2.0
 xattr>=0.9.2 # MIT
 python-swiftclient>=3.2.0 # Apache-2.0
-
-# Documentation
-os-api-ref>=1.4.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
-reno>=2.5.0 # Apache-2.0

tox.ini

@@ -69,6 +69,9 @@ commands =
 [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}/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
@@ -101,9 +104,12 @@ local-check-factory = glance.hacking.checks.factory
 import_exceptions = glance.i18n
 
 [testenv:docs]
+deps =
+    -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+    -r{toxinidir}/doc/requirements.txt
 commands =
   rm -fr doc/build
-  python setup.py build_sphinx
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:venv]
 commands = {posargs}
@@ -112,6 +118,9 @@ commands = {posargs}
 commands = bandit -c bandit.yaml -r glance -n5 -p gate
 
 [testenv:releasenotes]
+deps =
+    -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+    -r{toxinidir}/doc/requirements.txt
 commands =
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html