pydoctor.epydoc.markup.restructuredtext

module documentation

(source)

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 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	`DocutilsAndSphinxCodeBlockAdapter`	Undocumented
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`	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...
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 (...
Variable	`versionlabel_classes`	Undocumented
Variable	`versionlabels`	Undocumented
Class	`_DocumentPseudoWriter`	A pseudo-writer for the docutils framework, that can be used to access the document itself. The output of `_DocumentPseudoWriter` is just an empty string; but after it has been used, the most recently processed document is available as the instance variable ...
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: Documentable) -> ParserFunction: (source) ¶

Get the parse_docstring function.

def parse_docstring(docstring: str, errors: list[ParseError]) -> ParsedDocstring: (source) ¶

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.
Returns
`ParsedDocstring`	Undocumented

CONSOLIDATED_DEFLIST_FIELDS: list[str] = (source) ¶

Undocumented

Value

['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']

CONSOLIDATED_FIELDS: dict[str, str] = (source) ¶

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] = (source) ¶

Undocumented

versionlabels: dict[str, str] = (source) ¶

Undocumented