Merge "Switch to using pbr's autodoc capability"

3 files changed, 22 insertions, 104 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index dba80f0a..e38ab96a 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -3,6 +3,8 @@ from __future__ import print_function
 
 import sys
 import os
+import fileinput
+import fnmatch
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
@@ -13,107 +15,6 @@ sys.path.insert(0, BASE_DIR)
 # This is required for ReadTheDocs.org, but isn't a bad idea anyway.
 os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
 
-
-def write_autodoc_index():
-
-    def find_autodoc_modules(module_name, sourcedir):
-        """Return a list of modules in the SOURCE directory."""
-        modlist = []
-        os.chdir(os.path.join(sourcedir, module_name))
-        print("SEARCHING %s" % sourcedir)
-        for root, dirs, files in os.walk("."):
-            for filename in files:
-                if filename.endswith(".py"):
-                    # remove the pieces of the root
-                    elements = root.split(os.path.sep)
-                    # replace the leading "." with the module name
-                    elements[0] = module_name
-                    # and get the base module name
-                    base, extension = os.path.splitext(filename)
-                    if not (base == "__init__"):
-                        elements.append(base)
-                    result = ".".join(elements)
-                    #print result
-                    modlist.append(result)
-        return modlist
-
-    RSTDIR = os.path.abspath(os.path.join(BASE_DIR, "sourcecode"))
-    SRCS = {'openstack': ROOT}
-
-    EXCLUDED_MODULES = ()
-    CURRENT_SOURCES = {}
-
-    if not(os.path.exists(RSTDIR)):
-        os.mkdir(RSTDIR)
-    CURRENT_SOURCES[RSTDIR] = ['autoindex.rst']
-
-    INDEXOUT = open(os.path.join(RSTDIR, "autoindex.rst"), "w")
-    INDEXOUT.write("=================\n")
-    INDEXOUT.write("Source Code Index\n")
-    INDEXOUT.write("=================\n")
-
-    for modulename, path in SRCS.items():
-        sys.stdout.write("Generating source documentation for %s\n" %
-                         modulename)
-        INDEXOUT.write("\n%s\n" % modulename.capitalize())
-        INDEXOUT.write("%s\n" % ("=" * len(modulename),))
-        INDEXOUT.write(".. toctree::\n")
-        INDEXOUT.write("   :maxdepth: 1\n")
-        INDEXOUT.write("\n")
-
-        MOD_DIR = os.path.join(RSTDIR, modulename)
-        CURRENT_SOURCES[MOD_DIR] = []
-        if not(os.path.exists(MOD_DIR)):
-            os.mkdir(MOD_DIR)
-        for module in find_autodoc_modules(modulename, path):
-            if any([module.startswith(exclude)
-                    for exclude
-                    in EXCLUDED_MODULES]):
-                print("Excluded module %s." % module)
-                continue
-            mod_path = os.path.join(path, *module.split("."))
-            generated_file = os.path.join(MOD_DIR, "%s.rst" % module)
-
-            INDEXOUT.write("   %s/%s\n" % (modulename, module))
-
-            # Find the __init__.py module if this is a directory
-            if os.path.isdir(mod_path):
-                source_file = ".".join((os.path.join(mod_path, "__init__"),
-                                        "py",))
-            else:
-                source_file = ".".join((os.path.join(mod_path), "py"))
-
-            CURRENT_SOURCES[MOD_DIR].append("%s.rst" % module)
-            # Only generate a new file if the source has changed or we don't
-            # have a doc file to begin with.
-            if not os.access(generated_file, os.F_OK) or \
-                    os.stat(generated_file).st_mtime < \
-                    os.stat(source_file).st_mtime:
-                print("Module %s updated, generating new documentation." \
-                      % module)
-                FILEOUT = open(generated_file, "w")
-                header = "The :mod:`%s` Module" % module
-                FILEOUT.write("%s\n" % ("=" * len(header),))
-                FILEOUT.write("%s\n" % header)
-                FILEOUT.write("%s\n" % ("=" * len(header),))
-                FILEOUT.write(".. automodule:: %s\n" % module)
-                FILEOUT.write("  :members:\n")
-                FILEOUT.write("  :undoc-members:\n")
-                FILEOUT.write("  :show-inheritance:\n")
-                FILEOUT.write("  :noindex:\n")
-                FILEOUT.close()
-
-    INDEXOUT.close()
-    # Delete auto-generated .rst files for sources which no longer exist
-    for directory, subdirs, files in list(os.walk(RSTDIR)):
-        for old_file in files:
-            if old_file not in CURRENT_SOURCES.get(directory, []):
-                print("Removing outdated file for %s" % old_file)
-                os.remove(os.path.join(directory, old_file))
-
-
-write_autodoc_index()
-
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -125,6 +26,22 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
 
+# A list of glob-style patterns that should be excluded when looking for source
+# files.
+exclude_patterns = [
+    'api/tests.*',  # avoid of docs generation from tests
+    'api/openstack.common.cache._backends.*',
+]
+
+# Prune the excluded patterns from the autoindex
+for line in fileinput.input('api/autoindex.rst', inplace=True):
+    found = False
+    for pattern in exclude_patterns:
+        if fnmatch.fnmatch(line, '*' + pattern[4:]):
+            found = True
+    if not found:
+        print (line.rstrip())
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index cf41e559..9c4ea8d2 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,13 +3,13 @@ OpenStack Common Code
 
 Code shared across OpenStack.
 
-Contents
---------
+Code Documentation
+==================
 
 .. toctree::
    :maxdepth: 1
 
-   sourcecode/autoindex
+   api/autoindex
 
 Indices and tables
 ==================
diff --git a/setup.cfg b/setup.cfg
index 89b22822..7babdfd1 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -70,3 +70,4 @@ upload-dir = doc/build/html
 
 [pbr]
 warnerrors = true
+autodoc_index_modules = 1
\ No newline at end of file