From 58e06d8889fd7a88291b915b7d41a611e1dbf8c6 Mon Sep 17 00:00:00 2001
From: Shu Muto <shu-mutou@rf.jp.nec.com>
Date: Thu, 13 Jul 2017 15:47:34 +0900
Subject: [PATCH] Use pbr autodoc feature rather than custom logic

doc/source/conf.py has a custom logic which prepare index files
for autodoc, but now pbr and sphinx autodoc have a feature to do it
and it is not a good idea to keep the custom logic.

Change-Id: I99fceb0af1de0bd0f2c8aa25da232a4d63154cda
---
 doc/source/conf.py | 110 ---------------------------------------------
 setup.cfg          |   4 ++
 2 files changed, 4 insertions(+), 110 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8d69dd4..a3174df 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -45,116 +45,6 @@ django.setup()
 
 from zaqar_ui import version as zaqarui_ver
 
-
-def write_autodoc_index():
-
-    def find_autodoc_modules(module_name, sourcedir):
-        """returns 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 == 'tests.py':
-                    continue
-                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, "contributor/api"))
-    SRCS = [('zaqar_ui', 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("""
-=================
-Source Code Index
-=================
-
-.. contents::
-   :depth: 1
-   :local:
-
-""")
-
-    for modulename, path in SRCS:
-        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()
-
 # 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.
diff --git a/setup.cfg b/setup.cfg
index 9058c0c..ba90aa1 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -28,3 +28,7 @@ all_files = 1
 build-dir = doc/build
 source-dir = doc/source
 warning-is-error = 1
+
+[pbr]
+autodoc_index_modules = True
+api_doc_dir = contributor/api