Skip to content

sphinx ¤

This module defines functions to parse Sphinx docstrings into structured data.

Credits to Patrick Lannigan (@plannigan) who originally added the parser in the pytkdocs project. See https://github.com/mkdocstrings/pytkdocs/pull/71.

Classes:

  • FieldType –

    Maps directive names to parser functions.

  • ParsedDirective –

    Directive information that has been parsed from a docstring.

  • ParsedValues –

    Values parsed from the docstring to be used to produce sections.

Functions:

  • parse –

    Parse a Sphinx-style docstring.

FieldType dataclass ¤

FieldType(
    names: frozenset[str],
    reader: Callable[[Docstring, int, ParsedValues], int],
)

Maps directive names to parser functions.

Methods:

  • matches –

    Check if a line matches the field type.

matches ¤

matches(line: str) -> bool

Check if a line matches the field type.

Parameters:

  • line (str) –

    Line to check against

Returns:

  • bool –

    True if the line matches the field type, False otherwise.

ParsedDirective dataclass ¤

ParsedDirective(
    line: str,
    next_index: int,
    directive_parts: list[str],
    value: str,
    invalid: bool = False,
)

Directive information that has been parsed from a docstring.

ParsedValues dataclass ¤

ParsedValues(
    description: list[str] = list(),
    parameters: dict[str, DocstringParameter] = dict(),
    param_types: dict[str, str] = dict(),
    attributes: dict[str, DocstringAttribute] = dict(),
    attribute_types: dict[str, str] = dict(),
    exceptions: list[DocstringRaise] = list(),
    return_value: DocstringReturn | None = None,
    return_type: str | None = None,
)

Values parsed from the docstring to be used to produce sections.

parse ¤

parse(
    docstring: Docstring,
    *,
    warn_unknown_params: bool = True,
    **options: Any
) -> list[DocstringSection]

Parse a Sphinx-style docstring.

Parameters:

  • docstring (Docstring) –

    The docstring to parse.

  • warn_unknown_params (bool, default: True ) –

    Warn about documented parameters not appearing in the signature.

  • **options (Any, default: {} ) –

    Additional parsing options.

Returns: