Package epydoc :: Package markup :: Module restructuredtext

Module restructuredtext

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 `ParsedRstDocstring`s

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

An _EpydocReader is used to capture all error messages as it parses the docstring.
A _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 docutils.writers.html4css1.Writer, since those settings will be used when we actually write the docstring to html.

Using `ParsedRstDocstring`s

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

to_html() uses an _EpydocHTMLTranslator to translate the ParsedRstDocstring's document into an HTML segment.
split_fields() uses a _SplitFieldsTranslator to divide the ParsedRstDocstring's document into its main body and its fields. Special handling is done to account for consolidated fields.
summary() uses a _SummaryExtractor to extract the first sentence from the ParsedRstDocstring's document.
to_plaintext() uses document.astext() to convert the ParsedRstDocstring's document to plaintext.

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']

Module restructuredtext

Creating ParsedRstDocstrings

Using ParsedRstDocstrings

parse_docstring(docstring, errors, **options)

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

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

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

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

CONSOLIDATED_FIELDS

CONSOLIDATED_DEFLIST_FIELDS

Creating `ParsedRstDocstring`s

Using `ParsedRstDocstring`s