Fix docs publishing

Use sphinx-build so that the output happens in the right place.

Remove ChangeLog, instead link to the release notes.
Use apidoc for API doc building.

Fix main index page display so that title has higher level,
use link to OpenDev.

Change-Id: Iaa8d7f2143d411be31ad10b546455f18015566f3

doc/requirements.txt

@@ -5,6 +5,7 @@
 # These are needed for docs generation
 openstackdocstheme>=1.20.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 reno>=2.5.0 # Apache-2.0
 lxml!=3.7.0,>=3.4.1 # BSD
 fixtures>=3.0.0 # Apache-2.0/BSD

doc/source/conf.py

@@ -27,7 +27,7 @@ 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',
+extensions = ['sphinxcontrib.apidoc',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
               'sphinx.ext.intersphinx',
@@ -165,6 +165,13 @@ html_theme = 'openstackdocs'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'python-keystoneclientdoc'
 
+# -- sphinxcontrib.apidoc configuration --------------------------------------
+
+apidoc_module_dir = '../../keystoneclient'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'tests',
+]
 
 # -- Options for LaTeX output -------------------------------------------------
 

doc/source/history.rst

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

doc/source/index.rst

@@ -1,3 +1,4 @@
+========================================================
 Python bindings to the OpenStack Identity API (Keystone)
 ========================================================
 
@@ -27,19 +28,19 @@ provides `Identity Service`_, as well as `WSGI Middleware`_.
 Release Notes
 =============
 
-.. toctree::
-   :maxdepth: 1
 
-   history
+Read also the `Keystoneclient Release Notes
+<https://docs.openstack.org/releasenotes/python-keystoneclient/>`_.
+
 
 Contributing
 ============
 
-Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
+Code is hosted `on OpenDev`_. Submit bugs to the Keystone project on
 `Launchpad`_. Submit code to the ``openstack/python-keystoneclient`` project
 using `Gerrit`_.
 
-.. _on GitHub: https://github.com/openstack/python-keystoneclient
+.. _on OpenDev: https://opendev.org/openstack/python-keystoneclient
 .. _Launchpad: https://launchpad.net/python-keystoneclient
 .. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
 

tox.ini

@@ -64,7 +64,7 @@ show-source = True
 exclude = .venv,.tox,dist,doc,*egg,build
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 deps = -r{toxinidir}/doc/requirements.txt
 
 [testenv:pdf-docs]