From 249d1e992418fc7ff246c568e142f91db8a3a325 Mon Sep 17 00:00:00 2001
From: Colleen Murphy <colleen.murphy@suse.de>
Date: Thu, 26 Sep 2019 10:36:07 -0700
Subject: [PATCH] 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   |  1 +
 doc/source/conf.py     | 12 ++++++++++--
 doc/source/history.rst |  1 -
 doc/source/index.rst   | 14 +++++++-------
 tox.ini                |  2 +-
 5 files changed, 19 insertions(+), 11 deletions(-)
 delete mode 100644 doc/source/history.rst

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 4672c445..cc3595e5 100644
--- a/doc/requirements.txt
+++ b/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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 2a41a1af..0b3f65d7 100644
--- a/doc/source/conf.py
+++ b/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.
diff --git a/doc/source/history.rst b/doc/source/history.rst
deleted file mode 100644
index 69ed4fe6..00000000
--- a/doc/source/history.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../ChangeLog
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 83624f93..54c9458e 100644
--- a/doc/source/index.rst
+++ b/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`
diff --git a/tox.ini b/tox.ini
index cd0554d8..0da30287 100644
--- a/tox.ini
+++ b/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