pydoctor.epydoc.markup

package documentation

(source)

Markup language support for docstrings. Each submodule defines a parser for a single markup language. These parsers convert an object's docstring to a ParsedDocstring, a standard intermediate representation that can be used to generate output.

A ParsedDocstring is used for output generation (to_stan()). It also stores the fields that were extracted from the docstring during parsing (fields).

The parse_docstring() functions in the format modules take a docstring, parse it and return a format-specific subclass of ParsedDocstring. A docstring's fields are separated from the body during parsing.

The ParsedDocstring output generation method (to_stan()) uses a DocstringLinker to link the docstring output with the rest of the documentation that epydoc generates. DocstringLinkers are responsible for formatting cross-references (link_xref()).

Markup errors are represented using ParseErrors. These exception classes record information about the cause, location, and severity of each error.

Module	`epytext`	Parser for epytext strings. Epytext is a lightweight markup whose primary intended application is Python documentation strings. This parser converts Epytext strings to a simple DOM-like representation (encoded as a tree of ...
Module	`google`	Parser for google-style docstrings.
Module	`numpy`	Parser for numpy-style docstrings.
Module	`plaintext`	Parser for plaintext docstrings. Plaintext docstrings are rendered as verbatim output, preserving all whitespace.
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 ...
Module	`_napoleon`	This module contains a class to wrap shared behaviour between `pydoctor.epydoc.markup.numpy` and `pydoctor.epydoc.markup.google`.
Module	`_pyval_repr`	Syntax highlighter for Python values. Currently provides special colorization support for:
Module	`_types`	Render types from `docutils.nodes.document` objects.

From __init__.py:

Class	`DocstringLinker`	A resolver for crossreference links out of a `ParsedDocstring`. `DocstringLinker` is used by `ParsedDocstring` to look up the target URL for crossreference links.
Class	`Field`	The contents of a docstring's field. Docstring fields are used to describe specific aspects of an object, such as a parameter of a function or the author of a module. Each field consists of a tag, an optional argument, and a body:...
Class	`ParsedDocstring`	A standard intermediate representation for parsed docstrings that can be used to generate output. Parsed docstrings are produced by markup parsers such as `pydoctor.epydoc.markup.epytext.parse_docstring()`...
Class	`SummaryExtractor`	A docutils node visitor that extracts first sentences from the first paragraph in a document.
Exception	`ParseError`	The base class for errors generated while parsing docstrings.
Function	`append_warnings`	Utility method to create non fatal `ParseError`s and append them to the provided list.
Function	`get_parser_by_name`	Get the `parse_docstring(str, List[ParseError]) -> ParsedDocstring` function based on a parser name.
Function	`get_supported_docformats`	Get the list of currently supported docformat.
Function	`parsed_text`	Create a parsed representation of a simple text with a given class (or no class at all).
Function	`processtypes`	Wraps a docstring parser function to provide option --process-types.
Type Alias	`ObjClass`	A simpler version of `DocumentableKind` used for docstring parsing only.
Type Alias	`ParserFunction`	Undocumented

def append_warnings(warns: list[str], errs: list[ParseError], lineno: int): (source) ¶

Utility method to create non fatal ParseErrors and append them to the provided list.

Parameters
warns:`list[str]`	The warnings strings.
errs:`list[ParseError]`	The list of errors.
lineno:`int`	Undocumented

def get_parser_by_name(docformat: str, objclass: ObjClass | None = None) -> ParserFunction: (source) ¶

Get the parse_docstring(str, List[ParseError]) -> ParsedDocstring function based on a parser name.

Raises
`ImportError`	If the parser could not be imported, probably meaning that your are missing a dependency or it could be that the docformat name do not match any know `pydoctor.epydoc.markup` submodules.

def get_supported_docformats() -> Iterator[str]: (source) ¶

Get the list of currently supported docformat.

def parsed_text(text: str, klass: str | None = None, source: Literal['docstring', 'code'] = 'docstring') -> ParsedDocstring: (source) ¶

Create a parsed representation of a simple text with a given class (or no class at all).

The source is used for new_document call.

def processtypes(parse: ParserFunction) -> ParserFunction: (source) ¶

Wraps a docstring parser function to provide option --process-types.

ObjClass: TypeAlias = (source) ¶

A simpler version of DocumentableKind used for docstring parsing only.

Value

Literal['module', 'class', 'function', 'attribute']

ParserFunction = (source) ¶

Undocumented

Value

Callable[[str, list[ParseError]], ParsedDocstring]