diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | doc/source/api/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/conf.py | 114 | ||||
| -rw-r--r-- | doc/source/index.rst | 4 | ||||
| -rw-r--r-- | setup.cfg | 16 |
5 files changed, 27 insertions, 116 deletions
diff --git a/.gitignore b/.gitignore index 45c684656..b3044b5b3 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ cover .testrepository .project .pydevproject +doc/source/api/ diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 000000000..0e6b2a803 --- /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 f57621c7c..1620f5c3f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -57,120 +57,6 @@ cfg.CONF.set_override(name='environment_dir', override=TEMP_ENV_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) - modlist.append(result) - return modlist - - RSTDIR = os.path.abspath(os.path.join(BASE_DIR, "sourcecode")) - SOURCES = {'heat': {'module': 'heat', 'path': ROOT}} - - EXCLUDED_MODULES = ('heat.testing', - 'heat.cmd', - 'heat.common', - 'heat.cloudinit', - 'heat.cfn_client', - 'heat.doc', - 'heat.db', - 'heat.engine.resources', - 'heat.locale', - 'heat.openstack', - '.*\.tests', - '.*\.resources') - CURRENT_SOURCES = {} - - if not(os.path.exists(RSTDIR)): - os.mkdir(RSTDIR) - CURRENT_SOURCES[RSTDIR] = ['autoindex.rst', '.gitignore'] - - INDEXOUT = open(os.path.join(RSTDIR, "autoindex.rst"), "w") - INDEXOUT.write("=================\n") - INDEXOUT.write("Source Code Index\n") - INDEXOUT.write("=================\n") - - for title, info in SOURCES.items(): - path = info['path'] - modulename = info['module'] - sys.stdout.write("Generating source documentation for %s\n" % - title) - INDEXOUT.write("\n%s\n" % title.capitalize()) - INDEXOUT.write("%s\n" % ("=" * len(title),)) - INDEXOUT.write(".. toctree::\n") - INDEXOUT.write(" :maxdepth: 1\n") - INDEXOUT.write("\n") - - MOD_DIR = os.path.join(RSTDIR, title) - CURRENT_SOURCES[MOD_DIR] = [] - if not(os.path.exists(MOD_DIR)): - os.makedirs(MOD_DIR) - for module in find_autodoc_modules(modulename, path): - if any([re.match(exclude, module) - 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" % (title, 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 d9ed180ae..f525aa50b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -72,9 +72,9 @@ Operations Documentation Code Documentation ================== .. toctree:: - :maxdepth: 3 + :maxdepth: 1 - sourcecode/autoindex + api/autoindex Indices and tables ================== @@ -115,6 +115,22 @@ domain = heat output_dir = heat/locale input_file = heat/locale/heat.pot +[pbr] +autodoc_index_modules = true +autodoc_exclude_modules = + heat.testing.* + heat.cmd.* + heat.common.* + heat.cloudinit.* + heat.cfn_client.* + heat.doc.* + heat.db.* + heat.engine.resources.* + heat.locale.* + heat.openstack.* + *.tests.* + *.resources.* + [extract_messages] keywords = _ gettext ngettext l_ lazy_gettext mapping_file = babel.cfg |