Fixes documentation building

- Adds the ability to build docs using tox
 - Fixes autodoc generation

A Sphinx extension is introduced in the commit to facilitate building
the API documentation. This extension should be removed when
bug 1260495 is fixed.

Change-Id: Ibf5e5403cb7d3e67947c87b2828b64a56a11fc30

.gitignore

@@ -16,8 +16,8 @@ pep8.txt
 nosetests.xml
 doc/build
 .DS_Store
+doc/source/api
 doc/source/modules.rst
-doc/source/keystone.*
 ChangeLog
 AUTHORS
 build/

doc/README.rst

@@ -4,6 +4,6 @@ Building Docs
 Developer documentation is generated using Sphinx. To build this documentation,
 run the following from the root of the repository::
 
-  $ python setup.py build_sphinx
+  $ tox -e docs
 
 The documentation will be built at ``doc/build/``.

doc/ext/apidoc.py

@@ -0,0 +1,48 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2013 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(dstanek): Uncomment the [pbr] section in setup.cfg and remove this
+# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.
+
+import functools
+import os.path as path
+
+from sphinx import apidoc
+
+
+# NOTE(dstanek): 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 begining 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, '..', '..', 'keystone'))
+    source_dir = path.join(app.srcdir, 'api')
+    apidoc.main(['apidoc', package_dir, '-f',
+                 '-H', 'Keystone Modules',
+                 '-o', source_dir])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

doc/source/conf.py

@@ -18,7 +18,11 @@ import os
 # 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('../..'))
+sys.path.insert(0, os.path.abspath('..'))  # NOTE(dstanek): path for our
+                                           # Sphinx extension
+
+# NOTE(dstanek): adds _ to the builtins so keystone modules can be imported
+__builtins__['_'] = str
 
 # -- General configuration ----------------------------------------------------
 
@@ -31,7 +35,12 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
+              'sphinx.ext.viewcode',
               'oslo.sphinx',
+              # NOTE(dstanek): 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

doc/source/developing.rst

@@ -364,13 +364,8 @@ Example (using the above cacheable_function)::
 Building the Documentation
 ==========================
 
-The documentation is all generated with Sphinx from within the docs directory.
+The documentation is generated with Sphinx uning the tox command.  To create HTML docs and man pages::
-To generate the full set of HTML documentation::
 
-    cd docs
+    $ tox -e docs
-    make autodoc
-    make html
-    make man
 
-the results are in the docs/build/html and docs/build/man directories
+The results are in the docs/build/html and docs/build/man directories respectively.
-respectively.

doc/source/index.rst

@@ -75,7 +75,7 @@ Code Documentation
 .. toctree::
    :maxdepth: 1
 
-   api/autoindex
+   api/modules
 
 Indices and tables
 ==================

setup.cfg

@@ -55,3 +55,9 @@ mapping_file = babel.cfg
 output_file = keystone/locale/keystone.pot
 copyright_holder = OpenStack Foundation
 msgid_bugs_address = https://bugs.launchpad.net/keystone
+
+# NOTE(dstanek): Uncomment the [pbr] section below and remove the ext.apidoc
+# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.
+#[pbr]
+#autodoc_tree_index_modules = True
+#autodoc_tree_root = ./keystone

tox.ini

@@ -1,7 +1,7 @@
 [tox]
 minversion = 1.6
 skipsdist = True
-envlist = py26,py27,py33,pep8
+envlist = py26,py27,py33,pep8,docs
 
 [testenv]
 usedevelop = True
@@ -41,3 +41,7 @@ ignore = H803
 
 builtins = _
 exclude=.venv,.git,.tox,build,dist,doc,*openstack/common*,*lib/python*,*egg,tools,vendor,.update-venv,*.ini
+
+[testenv:docs]
+commands=
+    python setup.py build_sphinx