From e312b2419365e1964c65d0760cb5852c8b715a4c Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Wed, 10 Sep 2014 16:09:59 +0200 Subject: [PATCH] Switch to using pbr's autodoc capability Change-Id: I1cc51cf60a1493ad3a964b3fff50d9a681fdc858 --- .gitignore | 4 +- doc/source/api/index.rst | 8 +++ doc/source/conf.py | 102 --------------------------------------- doc/source/index.rst | 2 +- setup.cfg | 1 + 5 files changed, 12 insertions(+), 105 deletions(-) create mode 100644 doc/source/api/index.rst diff --git a/.gitignore b/.gitignore index 3380312f..291f25c9 100644 --- a/.gitignore +++ b/.gitignore @@ -9,8 +9,8 @@ build/* ChangeLog cover/* dist/* -doc/build/* -doc/source/sourcecode +doc/build +doc/source/api/ etc/ceilometer/ceilometer.conf subunit.log tools/lintstack.head.py diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 00000000..0e6b2a80 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,8 @@ +=================== + Source Code Index +=================== + +.. toctree:: + :maxdepth: 1 + + autoindex diff --git a/doc/source/conf.py b/doc/source/conf.py index 1d3ea5e8..fcddf70b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -23,108 +23,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 = {'ceilometer': ROOT} - - EXCLUDED_MODULES = ('ceilometer.tests',) - 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() - # 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/doc/source/index.rst b/doc/source/index.rst index fa86bec1..8cac5155 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -73,7 +73,7 @@ Appendix releasenotes/index glossary - sourcecode/autoindex + api/index .. update index diff --git a/setup.cfg b/setup.cfg index 761a6196..68737e14 100644 --- a/setup.cfg +++ b/setup.cfg @@ -360,6 +360,7 @@ source-dir = doc/source [pbr] warnerrors = true +autodoc_index_modules = true [extract_messages] keywords = _ gettext ngettext l_ lazy_gettext