Package epydoc :: Package markup :: Module restructuredtext
[hide private]
[frames] | no frames]

Module restructuredtext

source code

Epydoc parser for ReStructuredText strings. ReStructuredText is the standard markup language used by the Docutils project. parse_docstring() provides the primary interface to this module; it returns a ParsedRstDocstring, which supports all of the methods defined by ParsedDocstring.

ParsedRstDocstring is basically just a ParsedDocstring wrapper for the docutils.nodes.document class.

Creating ParsedRstDocstrings

ParsedRstDocstrings are created by the parse_document function, using the docutils.core.publish_string() method, with the following helpers:

Using ParsedRstDocstrings

ParsedRstDocstrings support all of the methods defined by ParsedDocstring; but only the following four methods have non-default behavior:


To Do: Add ParsedRstDocstring.to_latex()

Classes [hide private]
  OptimizedReporter
A reporter that ignores all debug messages.
  ParsedRstDocstring
An encoded version of a ReStructuredText docstring.
  _EpydocReader
A reader that captures all errors that are generated by parsing, and appends them to a list.
  _DocumentPseudoWriter
A pseudo-writer for the docutils framework, that can be used to access the document itself.
  _SummaryExtractor
A docutils node visitor that extracts the first sentence from the first paragraph in a document.
  _TermsExtractor
A docutils node visitor that extracts the terms from documentation.
  _SplitFieldsTranslator
A docutils translator that removes all fields from a document, and collects them into the instance variable fields
  _EpydocLaTeXTranslator
  _EpydocHTMLTranslator
    Graph Generation Directives
  dotgraph
A custom docutils node that should be rendered using Graphviz dot.
Functions [hide private]
ParsedDocstring
parse_docstring(docstring, errors, **options)
Parse the given docstring, which is formatted using ReStructuredText; and return a ParsedDocstring representation of its contents.
source code
call graph 
 
latex_head_prefix() source code
 
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.
source code
 
term_role(name, rawtext, text, lineno, inliner, options={}, content=[]) source code
    Graph Generation Directives
 
_dir_option(argument)
A directive option spec for the orientation of a graph.
source code
 
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.
source code
call graph 
 
_construct_digraph(docindex, context, linker, title, caption, body)
Graph generator for digraph_directive
source code
call graph 
 
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.
source code
call graph 
 
_construct_classtree(docindex, context, linker, arguments, options)
Graph generator for classtree_directive
source code
call graph 
 
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.
source code
call graph 
 
_construct_packagetree(docindex, context, linker, arguments, options)
Graph generator for packagetree_directive
source code
call graph 
 
importgraph_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine) source code
call graph 
 
_construct_importgraph(docindex, context, linker, arguments, options)
Graph generator for importgraph_directive
source code
call graph 
 
callgraph_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine) source code
 
_construct_callgraph(docindex, context, linker, arguments, options)
Graph generator for callgraph_directive
source code
Variables [hide private]
  CONSOLIDATED_FIELDS = {'arguments': 'arg', 'cvariables': 'cvar...
A dictionary encoding the set of 'consolidated fields' that can be used.
  CONSOLIDATED_DEFLIST_FIELDS = ['param', 'arg', 'var', 'ivar', ...
A list of consolidated fields whose bodies may be specified using a definition list, rather than a bulleted list.
Function Details [hide private]

parse_docstring(docstring, errors, **options)

source code 
call graph 
Parse the given docstring, which is formatted using ReStructuredText; and return a ParsedDocstring representation of its contents.
Parameters:
  • docstring (string) - The docstring to parse
  • errors (list of ParseError) - A list where any errors generated during parsing will be stored.
  • options - Extra options. Unknown options are ignored. Currently, no extra options are defined.
Returns: ParsedDocstring

python_code_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

source code 
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).

digraph_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

source code 
call graph 
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"]

classtree_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

source code 
call graph 

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:
  • :dir: -- Specifies the orientation of the graph. One of down, right (default), left, up.

packagetree_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

source code 
call graph 

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:
  • :dir: -- Specifies the orientation of the graph. One of down, right (default), left, up.

Variables Details [hide private]

CONSOLIDATED_FIELDS

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.
Value:
{'arguments': 'arg',
 'cvariables': 'cvar',
 'exceptions': 'except',
 'groups': 'group',
 'ivariables': 'ivar',
 'keywords': 'keyword',
 'parameters': 'param',
 'types': 'type',
...

CONSOLIDATED_DEFLIST_FIELDS

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.
Value:
['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']