IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Fix a few stylistic things, and add docs for autosummary_generate.

Browse Source
This commit is contained in:
Georg Brandl 2009-04-13 08:40:56 +00:00
parent ae1c7f9d56
commit 4d249fa3e4
4 changed files with 87 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
doc/ext/autosummary.rst
View File

@ -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.

14
sphinx/ext/autosummary/__init__.py
View File

@ -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<name>[a-zA_Z0-9_*]+)(?P<default>=.*?)?, ")
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]):

54
sphinx/ext/autosummary/generate.py
View File

@ -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()

4
tests/test_autosummary.py
View File

@ -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=<foo>) :: (a, b[, c, d])
(a, b, c='foobar()', d=123) :: (a, b[, c, d])
"""