pydoctor.epydoc.markup.restructuredtext

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	`OptimizedReporter`	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	`ParsedRstDocstring`	An encoded version of a ReStructuredText docstring. The contents of the docstring are encoded in the `_document` instance variable.
Class	`PythonCodeDirective`	No summary
Class	`SeeAlso`	An admonition mentioning things to look at as reference.
Class	`VersionChange`	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	`_DocumentPseudoWriter`	No summary
Class	`_EpydocReader`	A reader that captures all errors that are generated by parsing, and appends them to a list as `ParseError`.
Class	`_SplitFieldsTranslator`	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:`Documentable`	Undocumented
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:`str`	The docstring to parse
errors:`List[ParseError]`	A list where any errors generated during parsing will be stored.
processtypes:`bool`	Use `ParsedTypeDocstring` to parsed 'type' fields.
Returns
`ParsedDocstring`	Undocumented

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