module documentation

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_docstring 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.
Class ​Optimized​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.
Class ​Parsed​Rst​Docstring An encoded version of a ReStructuredText docstring. The contents of the docstring are encoded in the _document instance variable.
Class ​Python​Code​Directive No summary
Class ​See​Also An admonition mentioning things to look at as reference.
Class ​Version​Change Directive to describe a change/addition/deprecation in a specific version.
Function get​_parser Get the parse_docstring function.
Function parse​_docstring Parse the given docstring, which is formatted using ReStructuredText; and return a ParsedDocstring representation of its contents.
Constant CONSOLIDATED​_DEFLIST​_FIELDS Undocumented
Constant 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 (`...`). This module automatically splits these consolidated fields into individual fields. The keys of 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.
Variable versionlabel​_classes Undocumented
Variable versionlabels Undocumented
Class _​Document​Pseudo​Writer No summary
Class _​Epydoc​Reader A reader that captures all errors that are generated by parsing, and appends them to a list as ParseError.
Class _​Split​Fields​Translator A docutils translator that removes all fields from a document, and collects them into the instance variable fields
def get_parser(obj):
Get the parse_docstring function.
Parameters
obj:DocumentableUndocumented
Returns
Callable[[str, List[ParseError], bool], ParsedDocstring]Undocumented
def parse_docstring(docstring, errors, processtypes=False):
Parse the given docstring, which is formatted using ReStructuredText; and return a ParsedDocstring representation of its contents.
Parameters
docstring:strThe docstring to parse
errors:List[ParseError]A list where any errors generated during parsing will be stored.
processtypes:boolUse ParsedTypeDocstring to parsed 'type' fields.
Returns
ParsedDocstringUndocumented
CONSOLIDATED_DEFLIST_FIELDS: list[str] =

Undocumented

Value
['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']
CONSOLIDATED_FIELDS: dict[str, str] =
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 (`...`). This module automatically splits these consolidated fields into individual fields. The keys of 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.
Value
{'parameters': 'param',
 'arguments': 'arg',
 'exceptions': 'except',
 'variables': 'var',
 'ivariables': 'ivar',
 'cvariables': 'cvar',
 'groups': 'group',
...
versionlabel_classes: dict[str, str] =

Undocumented

versionlabels: dict[str, str] =

Undocumented