From 215ccba9ec25d8033f959247afbb3af6a0acf3b5 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Tue, 20 Sep 2016 21:17:20 +0000 Subject: [PATCH] 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 --- .gitignore | 1 - doc/source/conf.py | 111 ------------------------------------------- doc/source/index.rst | 10 ---- 3 files changed, 122 deletions(-) diff --git a/.gitignore b/.gitignore index 5138969c44..8a1c59f3cc 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index d26dc310f2..dd476027da 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index e5d49a51b2..9b8c053fda 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 =============