| # |
| # 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 as HTMLWriter |
| from docutils.writers.latex2e import LaTeXTranslator, Writer as LaTeXWriter |
| from docutils.readers.standalone import Reader as StandaloneReader |
| 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 |
| from epydoc.markup import * |
| 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) |
| |
