diff options
author | Brant Knudson <bknudson@us.ibm.com> | 2014-02-10 18:47:37 -0600 |
---|---|---|
committer | Brant Knudson <bknudson@us.ibm.com> | 2014-03-13 19:31:21 -0500 |
commit | fd59d02e933fe58aee93beddc9a4e655b3257e30 (patch) | |
tree | b99143a477f595b4952ce127a1e2d069c499ccd8 /doc | |
parent | f12afc6c738bf58688614a9b3d641fabb5bc5787 (diff) | |
download | python-keystoneclient-fd59d02e933fe58aee93beddc9a4e655b3257e30.tar.gz |
Generate module docs
The module docs were not being generated.
Co-Authored-By: David Stanek <dstanek@dstanek.com>
Change-Id: I26e1d9a3d407474eb6b016f3ada4c495b5043460
Closes-Bug: #1278662
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ext/__init__.py | 0 | ||||
-rw-r--r-- | doc/ext/apidoc.py | 46 | ||||
-rw-r--r-- | doc/source/conf.py | 13 |
3 files changed, 58 insertions, 1 deletions
diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/ext/__init__.py diff --git a/doc/ext/apidoc.py b/doc/ext/apidoc.py new file mode 100644 index 0000000..60ad23e --- /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 354d08c..e0e877e 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 |