diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 692eb911a..1fbf90504 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -6,33 +6,34 @@ .. module:: sphinx.ext.autosummary :synopsis: Generate autodoc summaries -.. versionadded: 0.6 +.. versionadded:: 0.6 -This extension generates function/method/attribute summary lists, -similar to those output eg. by Epydoc and other API doc generation -tools. This is especially useful when your docstrings are long and -detailed, and putting each one of them on a separate page makes -them easier to read. +This extension generates function/method/attribute summary lists, similar to +those output e.g. by Epydoc and other API doc generation tools. This is +especially useful when your docstrings are long and detailed, and putting each +one of them on a separate page makes them easier to read. The :mod:`sphinx.ext.autosummary` extension does this in two parts: - 1. There is an :dir:`autosummary` directive for generating summary - listings that contain links to the documented items, and short - summary blurbs extracted from their docstrings. +1. There is an :dir:`autosummary` directive for generating summary listings that + contain links to the documented items, and short summary blurbs extracted + from their docstrings. + +2. The convenience script :program:`sphinx-autogen` or the new + :confval:`autosummary_generate` config value can be used to generate short + "stub" files for the entries listed in the :dir:`autosummary` directives. + These by default contain only the corresponding :mod:`sphinx.ext.autodoc` + directive. - 2. The convenience script :program:`sphinx-autogen` can be used to - generate short "stub" files for the entries listed in the - :dir:`autosummary` directives. These by default contain only the - corresponding :mod:`sphinx.ext.autodoc` directive. .. directive:: autosummary - Insert a table that contains links to documented items, and a short - summary blurb (the first sentence of the docstring) for each of them. - The :dir:`autosummary` directive can also optionally serve as - a :dir:`toctree` entry for the included items. + Insert a table that contains links to documented items, and a short summary + blurb (the first sentence of the docstring) for each of them. The + :dir:`autosummary` directive can also optionally serve as a :dir:`toctree` + entry for the included items. - For example,:: + For example, :: .. currentmodule:: sphinx @@ -44,23 +45,23 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: produces a table like this: .. currentmodule:: sphinx - + .. autosummary:: - + environment.BuildEnvironment util.relative_uri - + .. currentmodule:: sphinx.ext.autosummary Autosummary preprocesses the docstrings and signatures with the same - :event:`autodoc-process-docstring` and - :event:`autodoc-process-signature` hooks as *autodoc*. + :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` + hooks as :mod:`~sphinx.ext.autodoc`. **Options** - * If you want the :dir:`autosummary` table to also serve as a - :dir:`toctree` entry, use the ``toctree`` option, for example:: + * If you want the :dir:`autosummary` table to also serve as a :dir:`toctree` + entry, use the ``toctree`` option, for example:: .. autosummary:: :toctree: DIRNAME @@ -68,14 +69,14 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: sphinx.environment.BuildEnvironment sphinx.util.relative_uri - The ``toctree`` option also signals to the :program:`sphinx-autogen` - script that stub pages should be generated for the entries listed - in this directive. The option accepts a directory name as an - argument; :program:`sphinx-autogen` will by default place its output - in this directory. + The ``toctree`` option also signals to the :program:`sphinx-autogen` script + that stub pages should be generated for the entries listed in this + directive. The option accepts a directory name as an argument; + :program:`sphinx-autogen` will by default place its output in this + directory. - * If you don't want the :dir:`autosummary` to show function signatures - in the listing, include the ``nosignatures`` option:: + * If you don't want the :dir:`autosummary` to show function signatures in the + listing, include the ``nosignatures`` option:: .. autosummary:: :nosignatures: @@ -83,26 +84,38 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: sphinx.environment.BuildEnvironment sphinx.util.relative_uri + :program:`sphinx-autogen` -- generate autodoc stub pages -------------------------------------------------------- -The :program:`sphinx-autogen` script can be used to conveniently -generate stub documentation pages for items included in -:dir:`autosummary` listings. +The :program:`sphinx-autogen` script can be used to conveniently generate stub +documentation pages for items included in :dir:`autosummary` listings. -For example, the command:: +For example, the command :: $ sphinx-autogen -o generated *.rst -will read all :dir:`autosummary` tables in the :file:`*.rst` files -that have the ``:toctree:`` option set, and output corresponding stub -pages in directory ``generated`` for all documented items. -The generated pages by default contain text of the form:: +will read all :dir:`autosummary` tables in the :file:`*.rst` files that have the +``:toctree:`` option set, and output corresponding stub pages in directory +``generated`` for all documented items. The generated pages by default contain +text of the form:: sphinx.util.relative_uri ======================== .. autofunction:: sphinx.util.relative_uri -If the ``-o`` option is not given, the script will place the output -files to the directories specified in the ``:toctree:`` options. +If the ``-o`` option is not given, the script will place the output files in the +directories specified in the ``:toctree:`` options. + + +Generating stub pages automatically +----------------------------------- + +If you do not want to create stub pages with :program:`sphinx-autogen`, you can +also use this new config value: + +.. confval:: autosummary_generate + + A list of documents for which stub pages should be generated. They will be + placed in the directories specified in the ``:toctree:`` options. diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index b34d35263..fc6e50397 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -108,6 +108,7 @@ def autosummary_toc_visit_latex(self, node): def autosummary_noop(self, node): pass + # -- autodoc integration ------------------------------------------------------- def get_documenter(obj): @@ -132,6 +133,7 @@ def get_documenter(obj): else: return autodoc.DataDocumenter + # -- .. autosummary:: ---------------------------------------------------------- class Autosummary(Directive): @@ -195,8 +197,7 @@ class Autosummary(Directive): def get_items(self, names): """ Try to import the given names, and return a list of - ``[(name, signature, summary_string, real_name), ...]`` - + ``[(name, signature, summary_string, real_name), ...]``. """ prefixes = [''] prefixes.insert(0, self.state.document.settings.env.currmodule) @@ -253,8 +254,7 @@ class Autosummary(Directive): """ Generate a proper table node for autosummary:: directive. - *items* is a list produced by :meth:`get_items` - + *items* is a list produced by :meth:`get_items`. """ table = nodes.table('') group = nodes.tgroup('', cols=2) @@ -291,10 +291,7 @@ class Autosummary(Directive): return table def mangle_signature(sig, max_chars=30): - """ - Reformat function signature to a more compact form. - - """ + """Reformat a function signature to a more compact form.""" sig = re.sub(r"^\((.*)\)$", r"\1", sig) + ", " r = re.compile(r"(?P[a-zA_Z0-9_*]+)(?P=.*?)?, ") items = r.findall(sig) @@ -327,6 +324,7 @@ def mangle_signature(sig, max_chars=30): sig = unicode(sig).replace(u" ", u"\u00a0") return u"(%s)" % sig + # -- Importing items ----------------------------------------------------------- def import_by_name(name, prefixes=[None]): diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 6b00f45f9..6bed2eb70 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -29,7 +29,8 @@ from jinja2 import Environment, PackageLoader from sphinx.ext.autosummary import import_by_name, get_documenter from sphinx.util import ensuredir -def main(argv): + +def main(argv=sys.argv): usage = """%prog [OPTIONS] SOURCEFILE ...""" p = optparse.OptionParser(usage.strip()) p.add_option("-o", "--output-dir", action="store", type="string", @@ -53,9 +54,7 @@ def _simple_info(msg): def _simple_warn(msg): print >>sys.stderr, 'WARNING: ' + msg -#------------------------------------------------------------------------------ -# Generating output -#------------------------------------------------------------------------------ +# -- Generating output --------------------------------------------------------- # create our own templating environment, for module template only env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) @@ -94,13 +93,13 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', try: if inspect.ismodule(obj): - # XXX replace this with autodoc's API? tmpl = env.get_template('module') def get_items(mod, typ): - return [getattr(mod, name).__name__ - for name in dir(mod) - if get_documenter(getattr(mod,name)).objtype==typ] + return [ + getattr(mod, name).__name__ for name in dir(mod) + if get_documenter(getattr(mod, name)).objtype == typ + ] functions = get_items(obj, 'function') classes = get_items(obj, 'class') @@ -139,15 +138,12 @@ def format_classmember(name, directive): return '.. currentmodule:: %s\n\n.. %s:: %s\n' % (mod, directive, name) -#------------------------------------------------------------------------------ -# Finding documented entries in files -#------------------------------------------------------------------------------ +# -- Finding documented entries in files --------------------------------------- def get_documented_in_files(filenames): """ - Find out what items are documented in source/*.rst + Find out what items are documented in source/*.rst. See `get_documented_in_lines`. - """ documented = {} for filename in filenames: @@ -161,7 +157,6 @@ def get_documented_in_docstring(name, module=None, filename=None): """ Find out what items are documented in the given object's docstring. See `get_documented_in_lines`. - """ try: obj, real_name = import_by_name(name) @@ -175,33 +170,30 @@ def get_documented_in_docstring(name, module=None, filename=None): def get_documented_in_lines(lines, module=None, filename=None): """ - Find out what items are documented in the given lines - - Returns - ------- - documented : dict of list of (filename, title, keyword, toctree) - Dictionary whose keys are documented names of objects. - The value is a list of locations where the object was documented. - Each location is a tuple of filename, the current section title, - the name of the directive, and the value of the :toctree: argument - (if present) of the directive. + Find out what items are documented in the given lines. + Returns a dict of lists of (filename, title, keyword, toctree) and whose + keys are documented names of objects. The value is a list of locations + where the object was documented. Each location is a tuple of filename, the + current section title, the name of the directive, and the value of the + :toctree: argument (if present) of the directive. """ title_underline_re = re.compile("^[-=*_^#]{3,}\s*$") - autodoc_re = re.compile(".. auto(function|method|attribute|class|exception|module)::\s*([A-Za-z0-9_.]+)\s*$") + autodoc_re = re.compile(r'.. auto(function|method|attribute|class|' + r'exception|module)::\s*([A-Za-z0-9_.]+)\s*$') autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*.*?') toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') - + documented = {} - + current_title = [] last_line = None toctree = None current_module = module in_autosummary = False - + for line in lines: try: if in_autosummary: @@ -216,12 +208,13 @@ def get_documented_in_lines(lines, module=None, filename=None): m = autosummary_item_re.match(line) if m: name = m.group(1).strip() - if current_module and not name.startswith(current_module + '.'): + if current_module and \ + not name.startswith(current_module + '.'): name = "%s.%s" % (current_module, name) documented.setdefault(name, []).append( (filename, current_title, 'autosummary', toctree)) continue - if line.strip() == '': + if not line.strip(): continue in_autosummary = False @@ -257,7 +250,6 @@ def get_documented_in_lines(lines, module=None, filename=None): return documented -#------------------------------------------------------------------------------ if __name__ == '__main__': main() diff --git a/tests/test_autosummary.py b/tests/test_autosummary.py index a748b2b73..d39131791 100644 --- a/tests/test_autosummary.py +++ b/tests/test_autosummary.py @@ -8,6 +8,7 @@ :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ + import string from util import * @@ -20,7 +21,8 @@ def test_mangle_signature(): () :: () (a, b, c, d, e) :: (a, b, c, d, e) (a, b, c=1, d=2, e=3) :: (a, b[, c, d, e]) - (a, b, aaa=1, bbb=1, ccc=1, eee=1, fff=1, ggg=1, hhh=1, iii=1, jjj=1) :: (a, b[, aaa, bbb, ccc, eee, fff, ...]) + (a, b, aaa=1, bbb=1, ccc=1, eee=1, fff=1, ggg=1, hhh=1, iii=1, jjj=1)\ + :: (a, b[, aaa, bbb, ccc, eee, fff, ...]) (a, b, c=(), d=) :: (a, b[, c, d]) (a, b, c='foobar()', d=123) :: (a, b[, c, d]) """