From fd59d02e933fe58aee93beddc9a4e655b3257e30 Mon Sep 17 00:00:00 2001
From: Brant Knudson <bknudson@us.ibm.com>
Date: Mon, 10 Feb 2014 18:47:37 -0600
Subject: [PATCH] Generate module docs
The module docs were not being generated.
Co-Authored-By: David Stanek <dstanek@dstanek.com>
Change-Id: I26e1d9a3d407474eb6b016f3ada4c495b5043460
Closes-Bug: #1278662
---
doc/ext/__init__.py | 0
doc/ext/apidoc.py | 46 +++++++++++++++++++++++++++++++++++++++++++++
doc/source/conf.py | 13 ++++++++++++-
tox.ini | 5 +++++
4 files changed, 63 insertions(+), 1 deletion(-)
create mode 100644 doc/ext/__init__.py
create mode 100644 doc/ext/apidoc.py
diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/ext/apidoc.py b/doc/ext/apidoc.py
new file mode 100644
index 000000000..60ad23e80
--- /dev/null
+++ b/doc/ext/apidoc.py
@@ -0,0 +1,46 @@
+# Copyright 2014 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+# NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and remove this
+# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.
+
+import os.path as path
+
+from sphinx import apidoc
+
+
+# NOTE(blk-u): pbr will run Sphinx multiple times when it generates
+# documentation. Once for each builder. To run this extension we use the
+# 'builder-inited' hook that fires at the beginning of a Sphinx build.
+# We use ``run_already`` to make sure apidocs are only generated once
+# even if Sphinx is run multiple times.
+run_already = False
+
+
+def run_apidoc(app):
+ global run_already
+ if run_already:
+ return
+ run_already = True
+
+ package_dir = path.abspath(path.join(app.srcdir, '..', '..',
+ 'keystoneclient'))
+ source_dir = path.join(app.srcdir, 'api')
+ apidoc.main(['apidoc', package_dir, '-f',
+ '-H', 'keystoneclient Modules',
+ '-o', source_dir])
+
+
+def setup(app):
+ app.connect('builder-inited', run_apidoc)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 354d08ce3..e0e877eec 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -23,6 +23,12 @@ import pbr.version
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
'..', '..')))
+# NOTE(blk-u): Path for our Sphinx extension, remove when
+# https://launchpad.net/bugs/1260495 is fixed.
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
+ '..')))
+
+
# 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.
@@ -36,7 +42,12 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
- 'sphinx.ext.intersphinx']
+ 'sphinx.ext.intersphinx',
+ # NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and
+ # remove this Sphinx extension when
+ # https://launchpad.net/bugs/1260495 is fixed.
+ 'ext.apidoc',
+ ]
todo_include_todos = True
diff --git a/tox.ini b/tox.ini
index 93752221b..af4f33b84 100644
--- a/tox.ini
+++ b/tox.ini
@@ -39,3 +39,8 @@ commands =
ignore = F821,H304,H803
show-source = True
exclude = .venv,.tox,dist,doc,*egg,build
+
+[testenv:docs]
+commands=
+ python setup.py build_sphinx
+