doc: Do not generate no source code reference
horizon devref has both explicit autodoc directives and automatically generated source references. This causes a lot of 'WARNING: duplicate object description'. I think that we don't need source code references for most modules and it is better to have explicit API references of modules for which we need references. Thus this commit removes the logic to generate source references. This contributes a lot to reduce the number of sphinx warnings. Also reduces the required time of documentation build :-) Partial-Bug: #1411719 Partial-Bug: #1486222 Change-Id: Iba2bf3723cad159f4cfd1fff47e8114d9867e040
This commit is contained in:
Akihiro Motoki
Akihiro Motoki
parent
35d2becdd6
commit
215ccba9ec
1
.gitignore
vendored
1
.gitignore
vendored
@ -30,7 +30,6 @@ openstack_dashboard/test/integration_tests/local-horizon.conf
|
||||
openstack_dashboard/test/integration_tests/test_reports/
|
||||
openstack_dashboard/wsgi/horizon.wsgi
|
||||
doc/build/
|
||||
doc/source/sourcecode
|
||||
/static/
|
||||
integration_tests_screenshots/
|
||||
.venv
|
||||
|
||||
@ -43,117 +43,6 @@ import horizon.version
|
||||
django.setup()
|
||||
|
||||
|
||||
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, "sourcecode"))
|
||||
SRCS = [('horizon', ROOT),
|
||||
('openstack_dashboard', ROOT)]
|
||||
|
||||
EXCLUDED_MODULES = ('horizon.test',
|
||||
'openstack_dashboard.enabled',
|
||||
'openstack_dashboard.test',
|
||||
'openstack_dashboard.openstack.common',
|
||||
)
|
||||
CURRENT_SOURCES = {}
|
||||
|
||||
if not(os.path.exists(RSTDIR)):
|
||||
os.mkdir(RSTDIR)
|
||||
CURRENT_SOURCES[RSTDIR] = ['autoindex.rst']
|
||||
|
||||
with open(os.path.join(RSTDIR, "autoindex.rst"), "w") as INDEXOUT:
|
||||
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)
|
||||
with open(generated_file, "w") as FILEOUT:
|
||||
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")
|
||||
|
||||
# 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.
|
||||
|
||||
@ -118,16 +118,6 @@ In-depth documentation for Horizon and its APIs.
|
||||
ref/test
|
||||
ref/local_conf
|
||||
|
||||
Source Code Reference
|
||||
---------------------
|
||||
|
||||
Auto-generated reference for the complete source code.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
sourcecode/autoindex
|
||||
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user