#
# rst.py: ReStructuredText docstring parsing
# Edward Loper
#
# Created [06/28/03 02:52 AM]
# $Id: restructuredtext.py 1661 2007-11-07 12:59:34Z dvarrazzo $
#
"""
Epydoc parser for ReStructuredText strings. ReStructuredText is the
standard markup language used by the Docutils project.
L{parse_docstring()} provides the primary interface to this module; it
returns a L{ParsedRstDocstring}, which supports all of the methods
defined by L{ParsedDocstring}.
L{ParsedRstDocstring} is basically just a L{ParsedDocstring} wrapper
for the C{docutils.nodes.document} class.
Creating C{ParsedRstDocstring}s
===============================
C{ParsedRstDocstring}s are created by the C{parse_document} function,
using the C{docutils.core.publish_string()} method, with the following
helpers:
- An L{_EpydocReader} is used to capture all error messages as it
parses the docstring.
- A L{_DocumentPseudoWriter} is used to extract the document itself,
without actually writing any output. The document is saved for
further processing. The settings for the writer are copied from
C{docutils.writers.html4css1.Writer}, since those settings will
be used when we actually write the docstring to html.
Using C{ParsedRstDocstring}s
============================
C{ParsedRstDocstring}s support all of the methods defined by
C{ParsedDocstring}; but only the following four methods have
non-default behavior:
- L{to_html()<ParsedRstDocstring.to_html>} uses an
L{_EpydocHTMLTranslator} to translate the C{ParsedRstDocstring}'s
document into an HTML segment.
- L{split_fields()<ParsedRstDocstring.split_fields>} uses a
L{_SplitFieldsTranslator} to divide the C{ParsedRstDocstring}'s
document into its main body and its fields. Special handling
is done to account for consolidated fields.
- L{summary()<ParsedRstDocstring.summary>} uses a
L{_SummaryExtractor} to extract the first sentence from
the C{ParsedRstDocstring}'s document.
- L{to_plaintext()<ParsedRstDocstring.to_plaintext>} uses
C{document.astext()} to convert the C{ParsedRstDocstring}'s
document to plaintext.
@todo: Add ParsedRstDocstring.to_latex()
@var CONSOLIDATED_FIELDS: A dictionary encoding the set of
'consolidated fields' that can be used. Each consolidated field is
marked by a single tag, and contains a single bulleted list, where
each list item starts with an identifier, marked as interpreted text
(C{`...`}). This module automatically splits these consolidated
fields into individual fields. The keys of C{CONSOLIDATED_FIELDS} are
the names of possible consolidated fields; and the values are the
names of the field tags that should be used for individual entries in
the list.
"""
__docformat__ = 'epytext en'
# Imports
import re, os, os.path
from xml.dom.minidom import *
from docutils.core import publish_string
from docutils.writers import Writer
from docutils.writers.html4css1 import HTMLTranslator,Writer
from docutils.writers.latex2e import LaTeXTranslator,Writer
from docutils.readers.standalone import Reader
from docutils.utils import new_document
from docutils.nodes import NodeVisitor,Text,SkipChildren
from docutils.nodes import SkipNode,TreeCopyVisitor
from docutils.frontend import OptionParser
from docutils.parsers.rst import directives,roles
import docutils.nodes
import docutils.transforms.frontmatter
import docutils.transforms
import docutils.utils
from epydoc.compat import *# Backwards compatibility
fromepydoc.markup*
from epydoc.apidoc import ModuleDoc,ClassDoc
from epydoc.docwriter.dotgraph import *
from epydoc.docwriter.xlink import ApiLinkReader
from epydoc.markup.doctest import doctest_to_html,doctest_to_latex,\
HTMLDoctestColorizer
#: A dictionary whose keys are the "consolidated fields" that are
#: recognized by epydoc; and whose values are the corresponding epydoc
#: field names that should be used for the individual fields.
CONSOLIDATED_FIELDS = {
'parameters': 'param',
'arguments': 'arg',
'exceptions': 'except',
'variables': 'var',
'ivariables': 'ivar',
'cvariables': 'cvar',
'groups': 'group',
'types': 'type',
'keywords': 'keyword',
}
#: A list of consolidated fields whose bodies may be specified using a
#: definition list, rather than a bulleted list. For these fields, the
#: 'classifier' for each term in the definition list is translated into
#: a @type field.
CONSOLIDATED_DEFLIST_FIELDS = ['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']
def parse_docstring(docstring, errors, **options):
"""
Parse the given docstring, which is formatted using
ReStructuredText; and return a L{ParsedDocstring} representation
of its contents.
@param docstring: The docstring to parse
@type docstring: C{string}
@param errors: A list where any errors generated during parsing
will be stored.
@type errors: C{list} of L{ParseError}
@param options: Extra options. Unknown options are ignored.
Currently, no extra options are defined.
@rtype: L{ParsedDocstring}
"""
writer = _DocumentPseudoWriter()
reader = _EpydocReader(errors) # Outputs errors to the list.
publish_string(docstring, writer=writer, reader=reader,
settings_overrides={'report_level':10000,
'halt_level':10000,
'warning_stream':None})
return ParsedRstDocstring(writer.document)
class OptimizedReporter(docutils.utils.Reporter):
"""A reporter that ignores all debug messages. This is used to
shave a couple seconds off of epydoc's run time, since docutils
isn't very fast about processing its own debug messages."""
def debug(self, *args, **kwargs): pass
class ParsedRstDocstring(ParsedDocstring):
"""
An encoded version of a ReStructuredText docstring. The contents
of the docstring are encoded in the L{_document} instance
variable.
@ivar _document: A ReStructuredText document, encoding the
docstring.
@type _document: C{docutils.nodes.document}
"""
def __init__(self, document):
"""
@type document: C{docutils.nodes.document}
"""
self._document = document
# The default document reporter and transformer are not
# pickle-able; so replace them with stubs that are.
document.reporter = OptimizedReporter(
document.reporter.source, 'SEVERE', 'SEVERE', '')
document.transformer = docutils.transforms.Transformer(document)
def split_fields(self, errors=None):
# Inherit docs
if errors is None: errors = []
visitor = _SplitFieldsTranslator(self._document, errors)
self._document.walk(visitor)
if len(self._document.children) > 0:
return self, visitor.fields
else:
return None, visitor.fields
def summary(self):
# Inherit docs
visitor = _SummaryExtractor(self._document)
try: self._document.walk(visitor)
except docutils.nodes.NodeFound: pass
return visitor.summary, bool(visitor.other_docs)
# def concatenate(self, other):
# result = self._document.copy()
# for child in (self._document.get_children() +
# other._document.get_children()):
# visitor = TreeCopyVisitor(self._document)
# child.walkabout(visitor)
# result.append(visitor.get_tree_copy())
# return ParsedRstDocstring(result)
def to_html(self, docstring_linker, directory=None,
docindex=None, context=None, **options):
# Inherit docs
visitor = _EpydocHTMLTranslator(self._document, docstring_linker,
directory, docindex, context)
self._document.walkabout(visitor)
return ''.join(visitor.body)
def to_latex(self, docstring_linker, **options):
# Inherit docs
visitor = _EpydocLaTeXTranslator(self._document, docstring_linker)
self._document.walkabout(visitor)
return ''.join(visitor.body)
def to_plaintext(self, docstring_linker, **options):
# This is should be replaced by something better:
return self._document.astext()
def __repr__(self): return '<ParsedRstDocstring: ...>'
def index_terms(self):
visitor = _TermsExtractor(self._document)
self._document.walkabout(visitor)
return visitor.terms
class _EpydocReader(ApiLinkReader):
"""
A reader that captures all errors that are generated by parsing,
and appends them to a list.
"""
# Remove the DocInfo transform, to ensure that :author: fields are
# correctly handled. This needs to be handled differently
# depending on the version of docutils that's being used, because
# the default_transforms attribute was deprecated & replaced by
# get_transforms().
version = [int(v) for v in docutils.__version__.split('.')]
version += [ 0 ] * (3 - len(version))
if version < [0,4,0]:
default_transforms = list(ApiLinkReader.default_transforms)
try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo)
except ValueError: pass
else:
def get_transforms(self):
return [t for t in ApiLinkReader.get_transforms(self)
if t != docutils.transforms.frontmatter.DocInfo]
del version
def __init__(self, errors):
self._errors = errors
ApiLinkReader.__init__(self)
def new_document(self):
document = new_document(self.source.source_path, self.settings)
# Capture all warning messages.
document.reporter.attach_observer(self.report)
# These are used so we know how to encode warning messages:
self._encoding = document.reporter.encoding
self._error_handler = document.reporter.error_handler
# Return the new document.
return document
def report(self, error):
try: is_fatal = int(error['level']) > 2
except: is_fatal = 1
try: linenum = int(error['line'])
except: linenum = None
msg = ''.join([c.astext().encode(self._encoding, self._error_handler)
for c in error])
self._errors.append(ParseError(msg, linenum, is_fatal))
class _DocumentPseudoWriter(Writer):
"""
A pseudo-writer for the docutils framework, that can be used to
access the document itself. The output of C{_DocumentPseudoWriter}
is just an empty string; but after it has been used, the most
recently processed document is available as the instance variable
C{document}
@type document: C{docutils.nodes.document}
@ivar document: The most recently processed document.
"""
def __init__(self):
self.document = None
Writer.__init__(self)
def translate(self):
self.output = ''
class _SummaryExtractor(NodeVisitor):
"""
A docutils node visitor that extracts the first sentence from
the first paragraph in a document.
"""
def __init__(self, document):
NodeVisitor.__init__(self, document)
self.summary = None
self.other_docs = None
def visit_document(self, node):
self.summary = None
_SUMMARY_RE = re.compile(r'(\s*[\w\W]*?\.)(\s|$)')
def visit_paragraph(self, node):
if self.summary is not None:
# found a paragraph after the first one
self.other_docs = True
raise docutils.nodes.NodeFound('Found summary')
summary_pieces = []
# Extract the first sentence.
for child in node:
if isinstance(child, docutils.nodes.Text):
m = self._SUMMARY_RE.match(child.data)
if m:
summary_pieces.append(docutils.nodes.Text(m.group(1)))
other = child.data[m.end():]
if other and not other.isspace():
self.other_docs = True
break
summary_pieces.append(child)
summary_doc = self.document.copy() # shallow copy
summary_para = node.copy() # shallow copy
summary_doc[:] = [summary_para]
summary_para[:] = summary_pieces
self.summary = ParsedRstDocstring(summary_doc)
def visit_field(self, node):
raise SkipNode
def unknown_visit(self, node):
'Ignore all unknown nodes'
class _TermsExtractor(NodeVisitor):
"""
A docutils node visitor that extracts the terms from documentation.
Terms are created using the C{:term:} interpreted text role.
"""
def __init__(self, document):
NodeVisitor.__init__(self, document)
self.terms = None
"""
The terms currently found.
@type: C{list}
"""
def visit_document(self, node):
self.terms = []
self._in_term = False
def visit_emphasis(self, node):
if 'term' in node.get('classes'):
self._in_term = True
def depart_emphasis(self, node):
if 'term' in node.get('classes'):
self._in_term = False
def visit_Text(self, node):
if self._in_term:
doc = self.document.copy()
doc[:] = [node.copy()]
self.terms.append(ParsedRstDocstring(doc))
def unknown_visit(self, node):
'Ignore all unknown nodes'
def unknown_departure(self, node):
'Ignore all unknown nodes'
class _SplitFieldsTranslator(NodeVisitor):
"""
A docutils translator that removes all fields from a document, and
collects them into the instance variable C{fields}
@ivar fields: The fields of the most recently walked document.
@type fields: C{list} of L{Field<markup.Field>}
"""
ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD = True
"""If true, then consolidated fields are not required to mark
arguments with C{`backticks`}. (This is currently only
implemented for consolidated fields expressed as definition lists;
consolidated fields expressed as unordered lists still require
backticks for now."""
def __init__(self, document, errors):
NodeVisitor.__init__(self, document)
self._errors = errors
self.fields = []
self._newfields = {}
def visit_document(self, node):
self.fields = []
def visit_field(self, node):
# Remove the field from the tree.
node.parent.remove(node)
# Extract the field name & optional argument
tag = node[0].astext().split(None, 1)
tagname = tag[0]
if len(tag)>1: arg = tag[1]
else: arg = None
# Handle special fields:
fbody = node[1]
if arg is None:
for (list_tag, entry_tag) in CONSOLIDATED_FIELDS.items():
if tagname.lower() == list_tag:
try:
self.handle_consolidated_field(fbody, entry_tag)
return
except ValueError, e:
estr = 'Unable to split consolidated field '
estr += '"%s" - %s' % (tagname, e)
self._errors.append(ParseError(estr, node.line,
is_fatal=0))
# Use a @newfield to let it be displayed as-is.
if tagname.lower() not in self._newfields:
newfield = Field('newfield', tagname.lower(),
parse(tagname, 'plaintext'))
self.fields.append(newfield)
self._newfields[tagname.lower()] = 1
self._add_field(tagname, arg, fbody)
def _add_field(self, tagname, arg, fbody):
field_doc = self.document.copy()
for child in fbody: field_doc.append(child)
field_pdoc = ParsedRstDocstring(field_doc)
self.fields.append(Field(tagname, arg, field_pdoc))
def visit_field_list(self, node):
# Remove the field list from the tree. The visitor will still walk
# over the node's children.
node.parent.remove(node)
def handle_consolidated_field(self, body, tagname):
"""
Attempt to handle a consolidated section.
"""
if len(body) != 1:
raise ValueError('does not contain a single list.')
elif body[0].tagname == 'bullet_list':
self.handle_consolidated_bullet_list(body[0], tagname)
elif (body[0].tagname == 'definition_list' and
tagname in CONSOLIDATED_DEFLIST_FIELDS):
self.handle_consolidated_definition_list(body[0], tagname)
elif tagname in CONSOLIDATED_DEFLIST_FIELDS:
raise ValueError('does not contain a bulleted list or '
'definition list.')
else:
raise ValueError('does not contain a bulleted list.')
def handle_consolidated_bullet_list(self, items, tagname):
# Check the contents of the list. In particular, each list
# item should have the form:
# - `arg`: description...
n = 0
_BAD_ITEM = ("list item %d is not well formed. Each item must "
"consist of a single marked identifier (e.g., `x`), "
"optionally followed by a colon or dash and a "
"description.")
for item in items:
n += 1
if item.tagname != 'list_item' or len(item) == 0:
raise ValueError('bad bulleted list (bad child %d).' % n)
if item[0].tagname != 'paragraph':
if item[0].tagname == 'definition_list':
raise ValueError(('list item %d contains a definition '+
'list (it\'s probably indented '+
'wrong).') % n)
else:
raise ValueError(_BAD_ITEM % n)
if len(item[0]) == 0:
raise ValueError(_BAD_ITEM % n)
if item[0][0].tagname != 'title_reference':
raise ValueError(_BAD_ITEM % n)
# Everything looks good; convert to multiple fields.
for item in items:
# Extract the arg
arg = item[0][0].astext()
# Extract the field body, and remove the arg
fbody = item[:]
fbody[0] = fbody[0].copy()
fbody[0][:] = item[0][1:]
# Remove the separating ":", if present
if (len(fbody[0]) > 0 and
isinstance(fbody[0][0], docutils.nodes.Text)):
child = fbody[0][0]
if child.data[:1] in ':-':
child.data = child.data[1:].lstrip()
elif child.data[:2] in (' -', ' :'):
child.data = child.data[2:].lstrip()
# Wrap the field body, and add a new field
self._add_field(tagname, arg, fbody)
def handle_consolidated_definition_list(self, items, tagname):
# Check the list contents.
n = 0
_BAD_ITEM = ("item %d is not well formed. Each item's term must "
"consist of a single marked identifier (e.g., `x`), "
"optionally followed by a space, colon, space, and "
"a type description.")
for item in items:
n += 1
if (item.tagname != 'definition_list_item' or len(item) < 2 or
item[0].tagname != 'term' or
item[-1].tagname != 'definition'):
raise ValueError('bad definition list (bad child %d).' % n)
if len(item) > 3:
raise ValueError(_BAD_ITEM % n)
if not ((item[0][0].tagname == 'title_reference') or
(self.ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD and
isinstance(item[0][0], docutils.nodes.Text))):
raise ValueError(_BAD_ITEM % n)
for child in item[0][1:]:
if child.astext() != '':
raise ValueError(_BAD_ITEM % n)
# Extract it.
for item in items:
# The basic field.
arg = item[0][0].astext()
fbody = item[-1]
self._add_field(tagname, arg, fbody)
# If there's a classifier, treat it as a type.
if len(item) == 3:
type_descr = item[1]
self._add_field('type', arg, type_descr)
def unknown_visit(self, node):
'Ignore all unknown nodes'
def latex_head_prefix():
document = new_document('<fake>')
translator = _EpydocLaTeXTranslator(document, None)
return translator.head_prefix
class _EpydocLaTeXTranslator(LaTeXTranslator):
settings = None
def __init__(self, document, docstring_linker):
# Set the document's settings.
if self.settings is None:
settings = OptionParser([LaTeXWriter()]).get_default_values()
settings.output_encoding = 'utf-8'
self.__class__.settings = settings
document.settings = self.settings
LaTeXTranslator.__init__(self, document)
self._linker = docstring_linker
# Start at section level 3. (Unfortunately, we now have to
# set a private variable to make this work; perhaps the standard
# latex translator should grow an official way to spell this?)
self.section_level = 3
self._section_number = [0]*self.section_level
# Handle interpreted text (crossreferences)
def visit_title_reference(self, node):
target = self.encode(node.astext())
xref = self._linker.translate_identifier_xref(target, target)
self.body.append(xref)
raise SkipNode()
def visit_document(self, node): pass
def depart_document(self, node): pass
# For now, just ignore dotgraphs. [XXX]
def visit_dotgraph(self, node):
log.warning("Ignoring dotgraph in latex output (dotgraph "
"rendering for latex not implemented yet).")
raise SkipNode()
def visit_doctest_block(self, node):
self.body.append(doctest_to_latex(node[0].astext()))
raise SkipNode()
class _EpydocHTMLTranslator(HTMLTranslator):
settings = None
def __init__(self, document, docstring_linker, directory,
docindex, context):
self._linker = docstring_linker
self._directory = directory
self._docindex = docindex
self._context = context
# Set the document's settings.
if self.settings is None:
settings = OptionParser([HTMLWriter()]).get_default_values()
self.__class__.settings = settings
document.settings = self.settings
# Call the parent constructor.
HTMLTranslator.__init__(self, document)
# Handle interpreted text (crossreferences)
def visit_title_reference(self, node):
target = self.encode(node.astext())
xref = self._linker.translate_identifier_xref(target, target)
self.body.append(xref)
raise SkipNode()
def should_be_compact_paragraph(self, node):
if self.document.children == [node]:
return True
else:
return HTMLTranslator.should_be_compact_paragraph(self, node)
def visit_document(self, node): pass
def depart_document(self, node): pass
def starttag(self, node, tagname, suffix='\n', **attributes):
"""
This modified version of starttag makes a few changes to HTML
tags, to prevent them from conflicting with epydoc. In particular:
- existing class attributes are prefixed with C{'rst-'}
- existing names are prefixed with C{'rst-'}
- hrefs starting with C{'#'} are prefixed with C{'rst-'}
- hrefs not starting with C{'#'} are given target='_top'
- all headings (C{<hM{n}>}) are given the css class C{'heading'}
"""
# Get the list of all attribute dictionaries we need to munge.
attr_dicts = [attributes]
if isinstance(node, docutils.nodes.Node):
attr_dicts.append(node.attributes)
if isinstance(node, dict):
attr_dicts.append(node)
# Munge each attribute dictionary. Unfortunately, we need to
# iterate through attributes one at a time because some
# versions of docutils don't case-normalize attributes.
for attr_dict in attr_dicts:
for (key, val) in attr_dict.items():
# Prefix all CSS classes with "rst-"; and prefix all
# names with "rst-" to avoid conflicts.
if key.lower() in ('class', 'id', 'name'):
attr_dict[key] = 'rst-%s' % val
elif key.lower() in ('classes', 'ids', 'names'):
attr_dict[key] = ['rst-%s' % cls for cls in val]
elif key.lower() == 'href':
if attr_dict[key][:1]=='#':
attr_dict[key] = '#rst-%s' % attr_dict[key][1:]
else:
# If it's an external link, open it in a new
# page.
attr_dict['target'] = '_top'
# For headings, use class="heading"
if re.match(r'^h\d+$', tagname):
attributes['class'] = ' '.join([attributes.get('class',''),
'heading']).strip()
return HTMLTranslator.starttag(self, node, tagname, suffix,
**attributes)
def visit_dotgraph(self, node):
if self._directory is None: return # [xx] warning?
# Generate the graph.
graph = node.graph(self._docindex, self._context, self._linker)
if graph is None: return
# Write the graph.
image_url = '%s.gif' % graph.uid
image_file = os.path.join(self._directory, image_url)
self.body.append(graph.to_html(image_file, image_url))
raise SkipNode()
def visit_doctest_block(self, node):
pysrc = node[0].astext()
if node.get('codeblock'):
self.body.append(HTMLDoctestColorizer().colorize_codeblock(pysrc))
else:
self.body.append(doctest_to_html(pysrc))
raise SkipNode()
def visit_emphasis(self, node):
# Generate a corrent index term anchor
if 'term' in node.get('classes') and node.children:
doc = self.document.copy()
doc[:] = [node.children[0].copy()]
self.body.append(
self._linker.translate_indexterm(ParsedRstDocstring(doc)))
raise SkipNode()
HTMLTranslator.visit_emphasis(self, node)
def python_code_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""
A custom restructuredtext directive which can be used to display
syntax-highlighted Python code blocks. This directive takes no
arguments, and the body should contain only Python code. This
directive can be used instead of doctest blocks when it is
inconvenient to list prompts on each line, or when you would
prefer that the output not contain prompts (e.g., to make
copy/paste easier).
"""
required_arguments = 0
optional_arguments = 0
text = '\n'.join(content)
node = docutils.nodes.doctest_block(text, text, codeblock=True)
return [ node ]
python_code_directive.arguments = (0, 0, 0)
python_code_directive.content = True
directives.register_directive('python', python_code_directive)
def term_role(name, rawtext, text, lineno, inliner,
options={}, content=[]):
text = docutils.utils.unescape(text)
node = docutils.nodes.emphasis(rawtext, text, **options)
node.attributes['classes'].append('term')
return [node], []
roles.register_local_role('term', term_role)
######################################################################
#{ Graph Generation Directives
######################################################################
# See http://docutils.sourceforge.net/docs/howto/rst-directives.html
class dotgraph(docutils.nodes.image):
"""
A custom docutils node that should be rendered using Graphviz dot.
This node does not directly store the graph; instead, it stores a
pointer to a function that can be used to generate the graph.
This allows the graph to be built based on information that might
not be available yet at parse time. This graph generation
function has the following signature:
>>> def generate_graph(docindex, context, linker, *args):
... 'generates and returns a new DotGraph'
Where C{docindex} is a docindex containing the documentation that
epydoc has built; C{context} is the C{APIDoc} whose docstring
contains this dotgraph node; C{linker} is a L{DocstringLinker}
that can be used to resolve crossreferences; and C{args} is any
extra arguments that are passed to the C{dotgraph} constructor.
"""
def __init__(self, generate_graph_func, *generate_graph_args):
docutils.nodes.image.__init__(self)
self.graph_func = generate_graph_func
self.args = generate_graph_args
def graph(self, docindex, context, linker):
return self.graph_func(docindex, context, linker, *self.args)
def _dir_option(argument):
"""A directive option spec for the orientation of a graph."""
argument = argument.lower().strip()
if argument == 'right': return 'LR'
if argument == 'left': return 'RL'
if argument == 'down': return 'TB'
if argument == 'up': return 'BT'
raise ValueError('%r unknown; choose from left, right, up, down' %
argument)
def digraph_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""
A custom restructuredtext directive which can be used to display
Graphviz dot graphs. This directive takes a single argument,
which is used as the graph's name. The contents of the directive
are used as the body of the graph. Any href attributes whose
value has the form <name> will be replaced by the URL of the object
with that name. Here's a simple example::
.. digraph:: example_digraph
a -> b -> c
c -> a [dir=\"none\"]
"""
if arguments: title = arguments[0]
else: title = ''
return [ dotgraph(_construct_digraph, title, options.get('caption'),
'\n'.join(content)) ]
digraph_directive.arguments = (0, 1, True)
digraph_directive.options = {'caption': directives.unchanged}
digraph_directive.content = True
directives.register_directive('digraph', digraph_directive)
def _construct_digraph(docindex, context, linker, title, caption,
body):
"""Graph generator for L{digraph_directive}"""
graph = DotGraph(title, body, caption=caption)
graph.link(linker)
return graph
def classtree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""
A custom restructuredtext directive which can be used to
graphically display a class hierarchy. If one or more arguments
are given, then those classes and all their descendants will be
displayed. If no arguments are given, and the directive is in a
class's docstring, then that class and all its descendants will be
displayed. It is an error to use this directive with no arguments
in a non-class docstring.
Options:
- C{:dir:} -- Specifies the orientation of the graph. One of
C{down}, C{right} (default), C{left}, C{up}.
"""
return [ dotgraph(_construct_classtree, arguments, options) ]
classtree_directive.arguments = (0, 1, True)
classtree_directive.options = {'dir': _dir_option}
classtree_directive.content = False
directives.register_directive('classtree', classtree_directive)
def _construct_classtree(docindex, context, linker, arguments, options):
"""Graph generator for L{classtree_directive}"""
if len(arguments) == 1:
bases = [docindex.find(name, context) for name in
arguments[0].replace(',',' ').split()]
bases = [d for d in bases if isinstance(d, ClassDoc)]
elif isinstance(context, ClassDoc):
bases = [context]
else:
log.warning("Could not construct class tree: you must "
"specify one or more base classes.")
return None
return class_tree_graph(bases, linker, context, **options)
def packagetree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""
A custom restructuredtext directive which can be used to
graphically display a package hierarchy. If one or more arguments
are given, then those packages and all their submodules will be
displayed. If no arguments are given, and the directive is in a
package's docstring, then that package and all its submodules will
be displayed. It is an error to use this directive with no
arguments in a non-package docstring.
Options:
- C{:dir:} -- Specifies the orientation of the graph. One of
C{down}, C{right} (default), C{left}, C{up}.
"""
return [ dotgraph(_construct_packagetree, arguments, options) ]
packagetree_directive.arguments = (0, 1, True)
packagetree_directive.options = {
'dir': _dir_option,
'style': lambda a:directives.choice(a.lower(), ('uml', 'tree'))}
packagetree_directive.content = False
directives.register_directive('packagetree', packagetree_directive)
def _construct_packagetree(docindex, context, linker, arguments, options):
"""Graph generator for L{packagetree_directive}"""
if len(arguments) == 1:
packages = [docindex.find(name, context) for name in
arguments[0].replace(',',' ').split()]
packages = [d for d in packages if isinstance(d, ModuleDoc)]
elif isinstance(context, ModuleDoc):
packages = [context]
else:
log.warning("Could not construct package tree: you must "
"specify one or more root packages.")
return None
return package_tree_graph(packages, linker, context, **options)
def importgraph_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
return [ dotgraph(_construct_importgraph, arguments, options) ]
importgraph_directive.arguments = (0, 1, True)
importgraph_directive.options = {'dir': _dir_option}
importgraph_directive.content = False
directives.register_directive('importgraph', importgraph_directive)
def _construct_importgraph(docindex, context, linker, arguments, options):
"""Graph generator for L{importgraph_directive}"""
if len(arguments) == 1:
modules = [ docindex.find(name, context)
for name in arguments[0].replace(',',' ').split() ]
modules = [d for d in modules if isinstance(d, ModuleDoc)]
else:
modules = [d for d in docindex.root if isinstance(d, ModuleDoc)]
return import_graph(modules, docindex, linker, context, **options)
def callgraph_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
return [ dotgraph(_construct_callgraph, arguments, options) ]
callgraph_directive.arguments = (0, 1, True)
callgraph_directive.options = {'dir': _dir_option,
'add_callers': directives.flag,
'add_callees': directives.flag}
callgraph_directive.content = False
directives.register_directive('callgraph', callgraph_directive)
def _construct_callgraph(docindex, context, linker, arguments, options):
"""Graph generator for L{callgraph_directive}"""
if len(arguments) == 1:
docs = [docindex.find(name, context) for name in
arguments[0].replace(',',' ').split()]
docs = [doc for doc in docs if doc is not None]
else:
docs = [context]
return call_graph(docs, docindex, linker, context, **options)
|