diff --git a/.gitignore b/.gitignore
index fa8c99f3f3..cf339bbadd 100644
--- a/.gitignore
+++ b/.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/
diff --git a/doc/README.rst b/doc/README.rst
index 50a0a3ea3e..a9537b9a45 100644
--- a/doc/README.rst
+++ b/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/``.
diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/doc/ext/apidoc.py b/doc/ext/apidoc.py
new file mode 100644
index 0000000000..e96346d1f6
--- /dev/null
+++ b/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)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index cd585d68f5..9dcedd8ba5 100644
--- a/doc/source/conf.py
+++ b/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
diff --git a/doc/source/developing.rst b/doc/source/developing.rst
index 3a4e8ad6b4..94a8cc1d3a 100644
--- a/doc/source/developing.rst
+++ b/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.
-To generate the full set of HTML documentation::
+The documentation is generated with Sphinx uning the tox command.  To create HTML docs and man pages::
 
-    cd docs
-    make autodoc
-    make html
-    make man
+    $ tox -e docs
 
-the results are in the docs/build/html and docs/build/man directories
-respectively.
+The results are in the docs/build/html and docs/build/man directories respectively.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 111c8a42b6..2d6130f1c9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -75,7 +75,7 @@ Code Documentation
 .. toctree::
    :maxdepth: 1
 
-   api/autoindex
+   api/modules
 
 Indices and tables
 ==================
diff --git a/setup.cfg b/setup.cfg
index 6654aabd06..4ef1122a64 100644
--- a/setup.cfg
+++ b/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
diff --git a/tox.ini b/tox.ini
index 5edb28be45..f77b6da4d4 100644
--- a/tox.ini
+++ b/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