From 27a566db7fc35262957378c42c27ccc86ff83208 Mon Sep 17 00:00:00 2001 From: Shu Muto Date: Thu, 13 Jul 2017 14:27:01 +0900 Subject: [PATCH] Use pbr autodoc feature rather than custom logic 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 not a good idea to keep the custom logic. Change-Id: I89a277bde7c7b632c2208110bb9d34cd21f4e815 --- doc/source/conf.py | 110 ------------------------------- doc/source/contributor/api.rst | 10 +++ doc/source/contributor/index.rst | 10 +-- setup.cfg | 5 ++ 4 files changed, 20 insertions(+), 115 deletions(-) create mode 100644 doc/source/contributor/api.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 46228bbf..29de0453 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -45,116 +45,6 @@ django.setup() from magnum_ui import version as magnumui_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 = [('magnum_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 00000000..c2a3017a --- /dev/null +++ b/doc/source/contributor/api.rst @@ -0,0 +1,10 @@ +===================== +Source Code Reference +===================== + +.. toctree:: + :maxdepth: 1 + :glob: + + api/* + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index e0387524..e61b5d28 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -7,11 +7,11 @@ There is no topic specific to Magnum UI now. See `Horizon Developer Documents `__ -Source Code Reference ---------------------- +---- .. toctree:: - :glob: - :maxdepth: 1 + :glob: + :maxdepth: 1 + + api - api/autoindex diff --git a/setup.cfg b/setup.cfg index 24aa21cc..3042ce7b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -27,3 +27,8 @@ 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 +