From 87cebf1a070a2c8956ef2939f43d53bf826600e9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Jan 2011 19:20:22 +0100 Subject: [PATCH] #98: Add autopackage script. (Undocumented for now.) --- AUTHORS | 3 + CHANGES | 4 + setup.py | 1 + sphinx-apidoc.py | 15 +++ sphinx/apidoc.py | 263 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 286 insertions(+) create mode 100755 sphinx-apidoc.py create mode 100644 sphinx/apidoc.py diff --git a/AUTHORS b/AUTHORS index 3d6d478e7..2ce36fccf 100644 --- a/AUTHORS +++ b/AUTHORS @@ -8,12 +8,14 @@ Other contributors, listed alphabetically, are: * Andi Albrecht -- agogo theme * Henrique Bastos -- SVG support for graphviz extension * Daniel Bültmann -- todo extension +* Etienne Desautels -- apidoc module * Michael Droettboom -- inheritance_diagram extension * Charles Duffy -- original graphviz extension * Josip Dzolonga -- coverage builder * Horst Gutmann -- internationalization support * Martin Hans -- autodoc improvements * Dave Kuhlman -- original LaTeX writer +* Blaise Laflamme -- pyramid theme * Thomas Lamb -- linkcheck builder * Robert Lehmann -- gettext builder (GSOC project) * Dan MacKinlay -- metadata fixes @@ -31,6 +33,7 @@ Other contributors, listed alphabetically, are: * Antonio Valentino -- qthelp builder * Pauli Virtanen -- autodoc improvements, autosummary extension * Stefan van der Walt -- autosummary extension +* Thomas Waldmann -- apidoc module fixes * John Waltman -- Texinfo builder * Barry Warsaw -- setup command improvements * Sebastian Wiesner -- image handling, distutils support diff --git a/CHANGES b/CHANGES index d38e53086..caefdc0da 100644 --- a/CHANGES +++ b/CHANGES @@ -26,6 +26,10 @@ Release 1.1 (in development) * Add ``pyramid`` theme. +* #98: Added a ``sphinx-apidoc`` script that autogenerates a + hierarchy of source files containing autodoc directives to + document modules and packages. + * #472: linkcheck builder: Check links in parallel, use HTTP HEAD requests and allow configuring the timeout. New config values: :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`. diff --git a/setup.py b/setup.py index 3b1d2d911..c73facaa6 100644 --- a/setup.py +++ b/setup.py @@ -193,6 +193,7 @@ setup( 'console_scripts': [ 'sphinx-build = sphinx:main', 'sphinx-quickstart = sphinx.quickstart:main', + 'sphinx-apidoc = sphinx.apidoc:main', 'sphinx-autogen = sphinx.ext.autosummary.generate:main', ], 'distutils.commands': [ diff --git a/sphinx-apidoc.py b/sphinx-apidoc.py new file mode 100755 index 000000000..9cafb497d --- /dev/null +++ b/sphinx-apidoc.py @@ -0,0 +1,15 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" + Sphinx - Python documentation toolchain + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import sys + +if __name__ == '__main__': + from sphinx.apidoc import main + sys.exit(main(sys.argv)) diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py new file mode 100644 index 000000000..ca1420980 --- /dev/null +++ b/sphinx/apidoc.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +""" + sphinx.apidoc + ~~~~~~~~~~~~~ + + Parses a directory tree looking for Python modules and packages and creates + ReST files appropriately to create code documentation with Sphinx. It also + creates a modules index (named modules.). + + :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" +import os +import sys +import optparse +from os import path + +# automodule options +OPTIONS = [ + 'members', + 'undoc-members', + # 'inherited-members', # disabled because there's a bug in sphinx + 'show-inheritance', +] + +INITPY = '__init__.py' + +def makename(package, module): + """Join package and module with a dot.""" + # Both package and module can be None/empty. + if package: + name = package + if module: + name += '.' + module + else: + name = module + return name + +def write_file(name, text, opts): + """Write the output file for module/package .""" + fname = path.join(opts.destdir, "%s.%s" % (name, opts.suffix)) + if opts.dryrun: + print 'Would create file %s.' % fname + return + if not opts.force and path.isfile(fname): + print 'File %s already exists, skipping.' % fname + else: + print 'Creating file %s.' % fname + f = open(fname, 'w') + try: + f.write(text) + finally: + f.close() + +def format_heading(level, text): + """Create a heading of [1, 2 or 3 supported].""" + underlining = ['=', '-', '~', ][level-1] * len(text) + return '%s\n%s\n\n' % (text, underlining) + +def format_directive(module, package=None): + """Create the automodule directive and add the options.""" + directive = '.. automodule:: %s\n' % makename(package, module) + for option in OPTIONS: + directive += ' :%s:\n' % option + return directive + +def create_module_file(package, module, opts): + """Build the text of the file and write the file.""" + text = format_heading(1, '%s Module' % module) + #text += format_heading(2, ':mod:`%s` Module' % module) + text += format_directive(module, package) + write_file(makename(package, module), text, opts) + +def create_package_file(root, master_package, subroot, py_files, opts, subs): + """Build the text of the file and write the file.""" + package = path.split(root)[-1] + text = format_heading(1, '%s Package' % package) + # add each module in the package + for py_file in py_files: + if shall_skip(path.join(root, py_file)): + continue + is_package = py_file == INITPY + py_file = path.splitext(py_file)[0] + py_path = makename(subroot, py_file) + if is_package: + heading = ':mod:`%s` Package' % package + else: + heading = ':mod:`%s` Module' % py_file + text += format_heading(2, heading) + text += format_directive(is_package and subroot or py_path, + master_package) + text += '\n' + + # build a list of directories that are packages (they contain an INITPY file) + subs = [sub for sub in subs if path.isfile(path.join(root, sub, INITPY))] + # if there are some package directories, add a TOC for theses subpackages + if subs: + text += format_heading(2, 'Subpackages') + text += '.. toctree::\n\n' + for sub in subs: + text += ' %s.%s\n' % (makename(master_package, subroot), sub) + text += '\n' + + write_file(makename(master_package, subroot), text, opts) + +def create_modules_toc_file(master_package, modules, opts, name='modules'): + """ + Create the module's index. + """ + text = format_heading(1, '%s Modules' % opts.header) + text += '.. toctree::\n' + text += ' :maxdepth: %s\n\n' % opts.maxdepth + + modules.sort() + prev_module = '' + for module in modules: + # look if the module is a subpackage and, if yes, ignore it + if module.startswith(prev_module + '.'): + continue + prev_module = module + text += ' %s\n' % module + + write_file(name, text, opts) + +def shall_skip(module): + """ + Check if we want to skip this module. + """ + # skip it, if there is nothing (or just \n or \r\n) in the file + return path.getsize(module) < 3 + +def recurse_tree(rootpath, excludes, opts): + """ + Look for every file in the directory tree and create the corresponding + ReST files. + """ + # check if the base directory is a package and get is name + if INITPY in os.listdir(rootpath): + package_name = path.abspath(rootpath).split(path.sep)[-1] + else: + package_name = None + + toc = [] + tree = os.walk(rootpath, False) + for root, subs, files in tree: + # keep only the Python script files + py_files = sorted([f for f in files if path.splitext(f)[1] == '.py']) + if INITPY in py_files: + py_files.remove(INITPY) + py_files.insert(0, INITPY) + # remove hidden ('.') and private ('_') directories + subs = sorted([sub for sub in subs if sub[0] not in ['.', '_']]) + # check if there are valid files to process + # TODO: could add check for windows hidden files + if "/." in root or "/_" in root \ + or not py_files \ + or is_excluded(root, excludes): + continue + if INITPY in py_files: + # we are in package ... + if (# ... with subpackage(s) + subs + or + # ... with some module(s) + len(py_files) > 1 + or + # ... with a not-to-be-skipped INITPY file + not shall_skip(path.join(root, INITPY)) + ): + subroot = root[len(rootpath):].lstrip(path.sep).\ + replace(path.sep, '.') + create_package_file(root, package_name, subroot, + py_files, opts, subs) + toc.append(makename(package_name, subroot)) + elif root == rootpath: + # if we are at the root level, we don't require it to be a package + for py_file in py_files: + if not shall_skip(path.join(rootpath, py_file)): + module = path.splitext(py_file)[0] + create_module_file(package_name, module, opts) + toc.append(makename(package_name, module)) + + # create the module's index + if not opts.notoc: + create_modules_toc_file(package_name, toc, opts) + +def normalize_excludes(rootpath, excludes): + """ + Normalize the excluded directory list: + * must be either an absolute path or start with rootpath, + * otherwise it is joined with rootpath + * with trailing slash + """ + sep = path.sep + f_excludes = [] + for exclude in excludes: + if not path.isabs(exclude) and not exclude.startswith(rootpath): + exclude = path.join(rootpath, exclude) + if not exclude.endswith(sep): + exclude += sep + f_excludes.append(exclude) + return f_excludes + +def is_excluded(root, excludes): + """ + Check if the directory is in the exclude list. + + Note: by having trailing slashes, we avoid common prefix issues, like + e.g. an exlude "foo" also accidentally excluding "foobar". + """ + sep = path.sep + if not root.endswith(sep): + root += sep + for exclude in excludes: + if root.startswith(exclude): + return True + return False + +def main(argv): + """ + Parse and check the command line arguments. + """ + parser = optparse.OptionParser( + usage="""\ +usage: %prog [options] -o [exclude_paths, ...] + +Look recursively in for Python modules and packages and create +a reST file with automodule directives per package in the . + +Note: By default this script will not overwrite already created files.""") + + parser.add_option('-o', '--output-dir', action='store', dest='destdir', + help='Directory to place all output', default='') + parser.add_option('-d', '--maxdepth', action='store', dest='maxdepth', + help='Maximum depth of submodules to show in the TOC ' + '(default: 4)', type='int', default=4) + parser.add_option('-f', '--force', action='store_true', dest='force', + help='Overwrite all the files') + parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun', + help='Run the script without creating the files') + parser.add_option('-T', '--no-toc', action='store_true', dest='notoc', + help='Don\'t create the table of contents file') + parser.add_option('-H', '--doc-header', action='store', dest='header', + help='Documentation Header (default: Project)', + default='Project') + parser.add_option('-s', '--suffix', action='store', dest='suffix', + help='file suffix (default: rst)', default='rst') + + (opts, args) = parser.parse_args(argv[1:]) + + if not args: + parser.error('A package path is required.') + if not opts.destdir: + parser.error('An output directory is required.') + rootpath, excludes = args[0], args[1:] + if not path.isdir(rootpath): + print >>sys.stderr, '%s is not a directory.' % rootpath + sys.exit(1) + if not path.isdir(opts.destdir): + print '%s is not a valid output directory.' % opts.destdir + sys.exit(1) + excludes = normalize_excludes(rootpath, excludes) + recurse_tree(rootpath, excludes, opts)