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

Work a bit on coding style of autosummary.

Browse Source
This commit is contained in:
Georg Brandl 2009-03-14 21:08:52 +01:00
parent ce4d9c3665
commit c85d4c2db2
4 changed files with 197 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
sphinx-autogen.py Executable file
View File

@ -0,0 +1,15 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: 2007-2009 by Georg Brandl.
:license: BSD.
"""
import sys
if __name__ == '__main__':
from sphinx.ext.autosummary.generate import main
sys.exit(main(sys.argv))

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

@ -1,18 +1,18 @@
# -*- coding: utf-8 -*-
""" """
=========== sphinx.ext.autosummary
autosummary ~~~~~~~~~~~~~~~~~~~~~~
===========
Sphinx extension that adds an autosummary:: directive, which can be Sphinx extension that adds an autosummary:: directive, which can be
used to generate function/method/attribute/etc. summary lists, similar used to generate function/method/attribute/etc. summary lists, similar
to those output eg. by Epydoc and other API doc generation tools. to those output eg. by Epydoc and other API doc generation tools.
An :autolink: role is also provided. An :autolink: role is also provided.
autosummary directive autosummary directive
--------------------- ---------------------
The autosummary directive has the form:: The autosummary directive has the form::
.. autosummary:: .. autosummary::
:nosignatures: :nosignatures:
@ -22,7 +22,7 @@ The autosummary directive has the form::
module.function_2 module.function_2
... ...
and it generates an output table (containing signatures, optionally) and it generates an output table (containing signatures, optionally)
======================== ============================================= ======================== =============================================
module.function_1(args) Summary line from the docstring of function_1 module.function_1(args) Summary line from the docstring of function_1
@ -30,51 +30,44 @@ and it generates an output table (containing signatures, optionally)
... ...
======================== ============================================= ======================== =============================================
If the :toctree: option is specified, files matching the function names If the :toctree: option is specified, files matching the function names
are inserted to the toctree with the given prefix: are inserted to the toctree with the given prefix:
generated/module.function_1 generated/module.function_1
generated/module.function_2 generated/module.function_2
... ...
Note: The file names contain the module:: or currentmodule:: prefixes. Note: The file names contain the module:: or currentmodule:: prefixes.
.. seealso:: autosummary_generate.py .. seealso:: autosummary_generate.py
autolink role autolink role
------------- -------------
The autolink role functions as ``:obj:`` when the name referred can be The autolink role functions as ``:obj:`` when the name referred can be
resolved to a Python object, and otherwise it becomes simple emphasis. resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'. This can be used as the default role to make links 'smart'.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
""" """
import sys, os, posixpath, re
import os
import re
import sys
import inspect
import posixpath
from docutils.parsers.rst import directives from docutils.parsers.rst import directives
from docutils.statemachine import ViewList from docutils.statemachine import ViewList
from docutils import nodes from docutils import nodes
import sphinx.addnodes, sphinx.roles, sphinx.builder from sphinx import addnodes, roles
from sphinx.util import patfilter from sphinx.util import patfilter
import inspect
def setup(app): # -- autosummary_toc node ------------------------------------------------------
app.add_directive('autosummary', autosummary_directive, True, (0, 0, False),
toctree=directives.unchanged,
nosignatures=directives.flag)
app.add_role('autolink', autolink_role)
app.add_node(autosummary_toc,
html=(autosummary_toc_visit_html, autosummary_toc_depart_noop),
latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop))
app.connect('doctree-read', process_autosummary_toc)
#------------------------------------------------------------------------------
# autosummary_toc node
#------------------------------------------------------------------------------
class autosummary_toc(nodes.comment): class autosummary_toc(nodes.comment):
pass pass
@ -83,7 +76,6 @@ def process_autosummary_toc(app, doctree):
""" """
Insert items described in autosummary:: to the TOC tree, but do Insert items described in autosummary:: to the TOC tree, but do
not generate the toctree:: list. not generate the toctree:: list.
""" """
env = app.builder.env env = app.builder.env
crawled = {} crawled = {}
@ -92,7 +84,7 @@ def process_autosummary_toc(app, doctree):
for j, subnode in enumerate(node): for j, subnode in enumerate(node):
try: try:
if (isinstance(subnode, autosummary_toc) if (isinstance(subnode, autosummary_toc)
and isinstance(subnode[0], sphinx.addnodes.toctree)): and isinstance(subnode[0], addnodes.toctree)):
env.note_toctree(env.docname, subnode[0]) env.note_toctree(env.docname, subnode[0])
continue continue
except IndexError: except IndexError:
@ -104,19 +96,18 @@ def process_autosummary_toc(app, doctree):
crawl_toc(doctree) crawl_toc(doctree)
def autosummary_toc_visit_html(self, node): def autosummary_toc_visit_html(self, node):
"""Hide autosummary toctree list in HTML output""" """Hide autosummary toctree list in HTML output."""
raise nodes.SkipNode raise nodes.SkipNode
def autosummary_toc_visit_latex(self, node): def autosummary_toc_visit_latex(self, node):
"""Show autosummary toctree (= put the referenced pages here) in Latex""" """Show autosummary toctree (= put the referenced pages here) in Latex."""
pass pass
def autosummary_toc_depart_noop(self, node): def autosummary_toc_depart_noop(self, node):
pass pass
#------------------------------------------------------------------------------
# .. autosummary:: # -- .. autosummary:: ----------------------------------------------------------
#------------------------------------------------------------------------------
def autosummary_directive(dirname, arguments, options, content, lineno, def autosummary_directive(dirname, arguments, options, content, lineno,
content_offset, block_text, state, state_machine): content_offset, block_text, state, state_machine):
@ -155,7 +146,7 @@ def autosummary_directive(dirname, arguments, options, content, lineno,
line=lineno)) line=lineno))
docnames.append(docname) docnames.append(docname)
tocnode = sphinx.addnodes.toctree() tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames tocnode['includefiles'] = docnames
tocnode['maxdepth'] = -1 tocnode['maxdepth'] = -1
tocnode['glob'] = None tocnode['glob'] = None
@ -165,6 +156,7 @@ def autosummary_directive(dirname, arguments, options, content, lineno,
else: else:
return warnings + [node] return warnings + [node]
def get_autosummary(names, state, no_signatures=False): def get_autosummary(names, state, no_signatures=False):
""" """
Generate a proper table node for autosummary:: directive. Generate a proper table node for autosummary:: directive.
@ -209,14 +201,14 @@ def get_autosummary(names, state, no_signatures=False):
except ImportError: except ImportError:
warnings.append(document.reporter.warning( warnings.append(document.reporter.warning(
'failed to import %s' % name)) 'failed to import %s' % name))
append_row(":obj:`%s`" % name, "") append_row(':obj:`%s`' % name, '')
continue continue
real_names[name] = real_name real_names[name] = real_name
title = "" title = ''
qualifier = 'obj' qualifier = 'obj'
col1 = ":"+qualifier+":`%s <%s>`" % (name, real_name) col1 = ':'+qualifier+':`%s <%s>`' % (name, real_name)
col2 = title col2 = title
append_row(col1, col2) append_row(col1, col2)
@ -254,9 +246,18 @@ def import_by_name(name, prefixes=[None]):
raise ImportError raise ImportError
def _import_by_name(name): def _import_by_name(name):
"""Import a Python object given its full name""" """Import a Python object given its full name."""
try: try:
# try first interpret `name` as MODNAME.OBJ
name_parts = name.split('.') name_parts = name.split('.')
try:
modname = '.'.join(name_parts[:-1])
__import__(modname)
return getattr(sys.modules[modname], name_parts[-1])
except (ImportError, IndexError, AttributeError):
pass
# ... then as MODNAME, MODNAME.OBJ1, MODNAME.OBJ1.OBJ2, ...
last_j = 0 last_j = 0
modname = None modname = None
for j in reversed(range(1, len(name_parts)+1)): for j in reversed(range(1, len(name_parts)+1)):
@ -279,19 +280,18 @@ def _import_by_name(name):
except (ValueError, ImportError, AttributeError, KeyError), e: except (ValueError, ImportError, AttributeError, KeyError), e:
raise ImportError(e) raise ImportError(e)
#------------------------------------------------------------------------------
# :autolink: (smart default role) # -- :autolink: (smart default role) -------------------------------------------
#------------------------------------------------------------------------------
def autolink_role(typ, rawtext, etext, lineno, inliner, def autolink_role(typ, rawtext, etext, lineno, inliner,
options={}, content=[]): options={}, content=[]):
""" """
Smart linking role. Smart linking role.
Expands to ":obj:`text`" if `text` is an object that can be imported; Expands to ':obj:`text`' if `text` is an object that can be imported;
otherwise expands to "*text*". otherwise expands to '*text*'.
""" """
r = sphinx.roles.xfileref_role('obj', rawtext, etext, lineno, inliner, r = roles.xfileref_role('obj', rawtext, etext, lineno, inliner,
options, content) options, content)
pnode = r[0][0] pnode = r[0][0]
@ -304,3 +304,15 @@ def autolink_role(typ, rawtext, etext, lineno, inliner,
r[0][0] = nodes.emphasis(rawtext, content[0].astext(), r[0][0] = nodes.emphasis(rawtext, content[0].astext(),
classes=content['classes']) classes=content['classes'])
return r return r
def setup(app):
app.add_directive('autosummary', autosummary_directive, True, (0, 0, False),
toctree=directives.unchanged,
nosignatures=directives.flag)
app.add_role('autolink', autolink_role)
app.add_node(autosummary_toc,
html=(autosummary_toc_visit_html, autosummary_toc_depart_noop),
latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop))
app.connect('doctree-read', process_autosummary_toc)

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

@ -1,38 +1,41 @@
# -*- coding: utf-8 -*-
""" """
autosummary_generate.py OPTIONS FILES sphinx.ext.autosummary.generate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generate automatic RST source files for items referred to in Usable as a library or script to generate automatic RST source files for
autosummary:: directives. items referred to in autosummary:: directives.
Each generated RST file contains a single auto*:: directive which Each generated RST file contains a single auto*:: directive which
extracts the docstring of the referred item. extracts the docstring of the referred item.
Example Makefile rule:: Example Makefile rule::
generate: generate:
sphinx-autogen source/*.rst source/generated sphinx-autogen source/*.rst source/generated
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
""" """
import glob, re, inspect, os, optparse import os
from sphinx.ext.autosummary import import_by_name import re
import sys
import glob
import inspect
from jinja import Environment, PackageLoader from jinja2 import Environment, PackageLoader
from sphinx.ext.autosummary import import_by_name
from sphinx.util import ensuredir
# create our own templating environment, for module template only
env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates'))
def main():
p = optparse.OptionParser(__doc__.strip())
options, args = p.parse_args()
if len(args) <2: def generate_autosummary_docs(sources, output_dir=None):
p.error("wrong number of arguments")
print 'generating docs from:', args[:-1]
generate_autosummary_docs(args[:-1], args[-1])
def generate_autosummary_docs(source_dir, output_dir):
# read # read
names = {} names = {}
for name, loc in get_documented(source_dir).items(): for name, loc in get_documented(sources).items():
for (filename, sec_title, keyword, toctree) in loc: for (filename, sec_title, keyword, toctree) in loc:
if toctree is not None: if toctree is not None:
path = os.path.join(os.path.dirname(filename), toctree) path = os.path.join(os.path.dirname(filename), toctree)
@ -40,42 +43,45 @@ def generate_autosummary_docs(source_dir, output_dir):
# write # write
for name, path in sorted(names.items()): for name, path in sorted(names.items()):
if output_dir is not None:
path = output_dir path = output_dir
if not os.path.isdir(path): ensuredir(path)
os.makedirs(path)
try: try:
obj, name = import_by_name(name) obj, name = import_by_name(name)
except ImportError, e: except ImportError, e:
print "Failed to import '%s': %s" % (name, e) print >>sys.stderr, 'Failed to import %r: %s' % (name, e)
continue continue
fn = os.path.join(path, '%s.rst' % name) fn = os.path.join(path, '%s.rst' % name)
# skip it if it exists
if os.path.exists(fn): if os.path.isfile(fn):
# skip
continue continue
f = open(fn, 'w') f = open(fn, 'w')
try: try:
if inspect.ismodule(obj): if inspect.ismodule(obj):
tmpl = env.get_template('module.html') tmpl = env.get_template('module')
functions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isfunction(getattr(obj, item))] functions = [getattr(obj, item).__name__
classes = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and not issubclass(getattr(obj, item), Exception)] for item in dir(obj)
exceptions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] if inspect.isfunction(getattr(obj, item))]
classes = [getattr(obj, item).__name__
for item in dir(obj)
if inspect.isclass(getattr(obj, item))
and not issubclass(getattr(obj, item), Exception)]
exceptions = [getattr(obj, item).__name__
for item in dir(obj)
if inspect.isclass(getattr(obj, item))
and issubclass(getattr(obj, item), Exception)]
rendered = tmpl.render(name=name, rendered = tmpl.render(name=name,
functions=functions, functions=functions,
classes=classes, classes=classes,
exceptions=exceptions, exceptions=exceptions,
len_functions=len(functions), len_functions=len(functions),
len_classes=len(classes), len_classes=len(classes),
len_exceptions=len(exceptions) len_exceptions=len(exceptions))
)
f.write(rendered) f.write(rendered)
else: else:
f.write('%s\n%s\n\n' % (name, '='*len(name))) f.write('%s\n%s\n\n' % (name, '='*len(name)))
@ -96,38 +102,38 @@ def generate_autosummary_docs(source_dir, output_dir):
finally: finally:
f.close() f.close()
def format_modulemember(name, directive): def format_modulemember(name, directive):
parts = name.split('.') parts = name.split('.')
mod, name = '.'.join(parts[:-1]), parts[-1] mod, name = '.'.join(parts[:-1]), parts[-1]
return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) return '.. currentmodule:: %s\n\n.. %s:: %s\n' % (mod, directive, name)
def format_classmember(name, directive): def format_classmember(name, directive):
parts = name.split('.') parts = name.split('.')
mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:]) mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:])
return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) return '.. currentmodule:: %s\n\n.. %s:: %s\n' % (mod, directive, name)
title_underline_re = re.compile('^[-=*_^#]{3,}\s*$')
autodoc_re = re.compile(r'.. auto(function|method|attribute|class|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*$')
def get_documented(filenames): def get_documented(filenames):
""" """
Find out what items are documented in source/*.rst Find out what items are documented in the given filenames.
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.
Returns a dict of list of (filename, title, keyword, toctree) 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*$")
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 = {} documented = {}
for filename in filenames: for filename in filenames:
@ -153,8 +159,9 @@ def get_documented(filenames):
if m: if m:
name = m.group(1).strip() name = m.group(1).strip()
if current_module and not name.startswith(current_module + '.'): if current_module and \
name = "%s.%s" % (current_module, name) not name.startswith(current_module + '.'):
name = '%s.%s' % (current_module, name)
documented.setdefault(name, []).append( documented.setdefault(name, []).append(
(filename, current_title, 'autosummary', toctree)) (filename, current_title, 'autosummary', toctree))
continue continue
@ -170,12 +177,13 @@ def get_documented(filenames):
m = autodoc_re.search(line) m = autodoc_re.search(line)
if m: if m:
name = m.group(2).strip() name = m.group(2).strip()
if current_module and not name.startswith(current_module + '.'): if current_module and \
name = "%s.%s" % (current_module, name) not name.startswith(current_module + '.'):
if m.group(1) == "module": name = '%s.%s' % (current_module, name)
if m.group(1) == 'module':
current_module = name current_module = name
documented.setdefault(name, []).append( documented.setdefault(name, []).append(
(filename, current_title, "auto" + m.group(1), None)) (filename, current_title, 'auto' + m.group(1), None))
continue continue
m = title_underline_re.match(line) m = title_underline_re.match(line)
@ -191,5 +199,17 @@ def get_documented(filenames):
last_line = line last_line = line
return documented return documented
if __name__ == "__main__":
def main(args=None):
if args is None:
args = sys.argv[1:]
if len(args) < 2:
print >>sys.stderr, 'usage: %s sourcefile ... outputdir' % sys.argv[0]
print 'generating docs from:', ', '.join(args[:-1])
generate_autosummary_docs(args[:-1], args[-1])
if __name__ == '__main__':
main() main()

0
sphinx/ext/autosummary/templates/module.html → sphinx/ext/autosummary/templates/module
View File