From 496439b2ade8ece4ecaa8b7bb370b8d4aa4e5b54 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Tue, 11 Jul 2017 06:13:55 +0000 Subject: [PATCH] Use pbr autodoc feature rather than custom logic zun-ui doc/source/conf.py has a custom logic which prepare index files for autodoc, but now pbr and sphinx autodoc have a feature to do it and it is no a good idea to keep the custom logic. UI cookiecutter populates the custom logic and it is an example of the clean up. Change-Id: I6c6eb2f6292bda30a4fa8d4375defd8234463008 --- doc/source/conf.py | 109 ------------------------------- doc/source/contributor/api.rst | 9 +++ doc/source/contributor/index.rst | 6 +- setup.cfg | 4 ++ 4 files changed, 15 insertions(+), 113 deletions(-) create mode 100644 doc/source/contributor/api.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 502973e..4542619 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -46,115 +46,6 @@ django.setup() from zun_ui import version as zunui_ver -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, "contributor/api")) - SRCS = [('zun_ui', ROOT), ] - - EXCLUDED_MODULES = () - 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(""" -================= -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) - 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/contributor/api.rst b/doc/source/contributor/api.rst new file mode 100644 index 0000000..dd3be26 --- /dev/null +++ b/doc/source/contributor/api.rst @@ -0,0 +1,9 @@ +===================== +Source Code Reference +===================== + +.. toctree:: + :maxdepth: 1 + :glob: + + api/* diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 3937784..d4c6036 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -8,12 +8,10 @@ See `Horizon Developer Documents `__ for general topic on developing a dashboard on horizon. - -Source Code Reference ---------------------- +---- .. toctree:: :glob: :maxdepth: 1 - api/autoindex + api diff --git a/setup.cfg b/setup.cfg index ef9c59b..e9c9cd2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -27,3 +27,7 @@ all_files = 1 build-dir = doc/build source-dir = doc/source warning-is-error = 1 + +[pbr] +autodoc_index_modules = True +api_doc_dir = contributor/api