Skip to content

numpy ¤

This module defines functions to parse Numpy-style docstrings into structured data.

Based on https://numpydoc.readthedocs.io/en/latest/format.html, it seems Numpydoc is a superset of RST. Since fully parsing RST is a non-goal of this project, some things are stripped from the Numpydoc specification.

Rejected as non particularly Pythonic or useful as sections:

  • See also: this section feels too subjective (specially crafted as a standard for Numpy itself), and there are may ways to reference related items in a docstring, depending on the chosen markup.

Rejected as naturally handled by the user-chosen markup:

  • Warnings: this is just markup.
  • Notes: again, just markup.
  • References: again, just markup.

Functions:

  • parse –

    Parse a Numpydoc-style docstring.

parse ¤

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

Parse a Numpydoc-style docstring.

This function iterates on lines of a docstring to build sections. It then returns this list of sections.

Parameters:

  • docstring (Docstring) –

    The docstring to parse.

  • ignore_init_summary (bool, default: False ) –

    Whether to ignore the summary in __init__ methods' docstrings.

  • trim_doctest_flags (bool, default: True ) –

    Whether to remove doctest flags from Python example blocks.

  • warn_unknown_params (bool, default: True ) –

    Warn about documented parameters not appearing in the signature.

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

    Additional parsing options.

Returns: