From a9d01eef93eef576bcecabf54e86c3a7a49651c8 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Wed, 15 Apr 2020 10:40:01 +0200 Subject: 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 | 1 + doc/source/conf.py | 9 ++++++++- doc/source/history.rst | 1 - doc/source/index.rst | 11 ++++++----- tox.ini | 2 +- 5 files changed, 16 insertions(+), 8 deletions(-) delete mode 100644 doc/source/history.rst diff --git a/doc/requirements.txt b/doc/requirements.txt index c4f9c7d..1da2c50 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 751b01a..1dd272a 100644 --- a/doc/source/conf.py +++ b/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 ------------------------------------------------- diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index 69ed4fe..0000000 --- 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 bee9630..f1114b6 100644 --- a/doc/source/index.rst +++ b/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 +`_. + 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 diff --git a/tox.ini b/tox.ini index 28578a2..b1d7983 100644 --- a/tox.ini +++ b/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] -- cgit v1.2.1