Use pbr new autodoc feature

This relies on the new pbr feature that autogenerates the documentation.

Change-Id: Ie3287dfc6a9a4566eb1c444af63ae86954c69e68
changes/22/180122/3
Julien Danjou 7 years ago
parent 0b69e23038
commit 6015b725f7
  1. 1
      .gitignore
  2. 8
      doc/source/api/index.rst
  3. 114
      doc/source/conf.py
  4. 4
      doc/source/index.rst
  5. 16
      setup.cfg

1
.gitignore vendored

@ -19,3 +19,4 @@ cover
.testrepository
.project
.pydevproject
doc/source/api/

@ -0,0 +1,8 @@
===================
Source Code Index
===================
.. toctree::
:maxdepth: 1
autoindex

@ -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.

@ -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

Loading…
Cancel
Save