From 63d741fd6646b360818c07a9679344e889031949 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Tue, 3 Apr 2018 17:29:59 +0100
Subject: [PATCH] Replace pbr autodoc with sphinxcontrib-apidoc
This fixes local building of the documentation using tox, and allows the
gate to stop relying on pbr and move completely to the new docs PTI.
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html
Change-Id: I485acda07098a435753e91c1ca45e586de199c35
---
doc/requirements.txt | 3 ++-
doc/source/conf.py | 19 +++++++++++--------
setup.cfg | 16 ----------------
tox.ini | 5 +++--
4 files changed, 16 insertions(+), 27 deletions(-)
diff --git a/doc/requirements.txt b/doc/requirements.txt
index d959d4431b..1afc73d6a6 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -3,4 +3,5 @@
# process, which may cause wedges in the gate later.
openstackdocstheme>=1.18.1 # Apache-2.0
reno>=2.5.0 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD
+sphinxcontrib-apidoc>=0.2.0 # BSD
diff --git a/doc/source/conf.py b/doc/source/conf.py
index d7efbd7b91..003bfcaa34 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -12,16 +12,8 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
-import os
-import sys
-
import pbr.version
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
-
# -- General configuration ----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@@ -35,6 +27,7 @@ extensions = ['sphinx.ext.autodoc',
'openstackdocstheme',
'stevedore.sphinxext',
'cliff.sphinxext',
+ 'sphinxcontrib.apidoc',
]
# openstackdocstheme options
@@ -282,3 +275,13 @@ autoprogram_cliff_application = 'openstack'
autoprogram_cliff_ignored = [
'--help', '--format', '--column', '--max-width', '--fit-width',
'--print-empty', '--prefix', '--noindent', '--quote']
+
+
+# -- Options for sphinxcontrib.apidoc ----------------------------------------
+
+apidoc_module_dir = '../../openstackclient'
+apidoc_excluded_paths = [
+ 'volume/v3',
+ 'tests',
+]
+apidoc_output_dir = 'contributor/api'
diff --git a/setup.cfg b/setup.cfg
index ac45a77dcd..f9c0b3efcf 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -714,22 +714,6 @@ openstack.volume.v3 =
volume_transfer_request_list = openstackclient.volume.v2.volume_transfer_request:ListTransferRequest
volume_transfer_request_show = openstackclient.volume.v2.volume_transfer_request:ShowTransferRequest
-[pbr]
-autodoc_tree_index_modules = True
-autodoc_tree_excludes =
- setup.py
- openstackclient/volume/v3
- openstackclient/tests/
- openstackclient/tests/*
-api_doc_dir = contributor/api
-
-[build_sphinx]
-builders = html,man
-all-files = 1
-warning-is-error = 1
-source-dir = doc/source
-build-dir = doc/build
-
[upload_sphinx]
upload-dir = doc/build/html
diff --git a/tox.ini b/tox.ini
index 9c10eb2fb7..4aad012cd6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -113,12 +113,13 @@ deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
+commands =
+ sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
+ sphinx-build -a -E -W -d doc/build/doctrees -b man doc/source doc/build/man
[testenv:releasenotes]
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
- -r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands =
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html