Follow the PTI for docs

Use sphinx-build instead of the pbr sphinx extention for building docs
as instructed by the PTI[1].

This requires using the sphinxcontrib-apidoc plugin rather than the
autodoc pbr extention. We also remove the reference to the ChangeLog
file that is usually generated by pbr and instead refer to the published
reno release notes. Also fixes the header formatting for the index page,
as the headers weren't rendering at all.

[1] https://governance.openstack.org/tc/reference/pti/python.html

Change-Id: Iec8b99fa89877e357cf2e754abad77c9032acad1

doc/requirements.txt

@@ -7,6 +7,7 @@ openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7'  # BSD
 sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4'  # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 
 # For autodoc builds
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0

doc/source/conf.py

@@ -35,14 +35,22 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
 # 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.todo',
+extensions = ['sphinx.ext.todo',
               'sphinx.ext.coverage',
               'sphinx.ext.intersphinx',
               'openstackdocstheme',
               'ext.list_plugins',
+              'sphinxcontrib.apidoc',
              ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../keystoneauth1'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'tests',
+    'test']
+apidoc_separate_modules = True
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/history.rst

@@ -1 +0,0 @@
-.. include:: ../../ChangeLog

doc/source/index.rst

@@ -6,7 +6,8 @@ within the OpenStack ecosystem. It is designed for use in conjunction with the
 existing OpenStack clients and for simplifying the process of writing new
 clients.
 
-Contents:
+Contents
+--------
 
 .. toctree::
    :maxdepth: 1
@@ -21,15 +22,14 @@ Contents:
    api/modules
 
 Release Notes
-=============
+-------------
 
-.. toctree::
-   :maxdepth: 1
+`Release Notes`_
 
-   history
+.. _Release Notes: https://docs.openstack.org/releasenotes/keystoneauth/
 
 Contributing
-============
+------------
 
 Code is hosted `on opendev.org`_. Submit bugs to the Keystone project on
 `Launchpad`_. Submit code to the ``openstack/keystoneauth`` project
@@ -42,7 +42,7 @@ using `Gerrit`_.
 Run tests with ``tox``.
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

tox.ini

@@ -74,7 +74,7 @@ deps =
 commands =
     bash -c "rm -rf doc/build"
     bash -c "rm -rf doc/source/api"
-    python setup.py build_sphinx
+    sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
 
 [testenv:releasenotes]
 basepython = python3