dev.docs.docstrings

dev.docs.docstrings#

Helpers for parsing and rendering docstrings in Sphinx.

References#

Copyright 2023 Digital Biology, Inc., SPDX-License-Identifier: Apache-2.0, sphinx-extensions2/sphinx-autodoc2#33

Module Contents#

Classes#

MystNumpyDocHybridParser

Hybrid docstring. Use NumpyDoc style, but allow Markdown instead of rST.

Functions#

render_see_also

Render a single NumpyDoc “See Also” reference.

render_see_also_section

Render the full “See Also” section from parsed output of NumpyDoc.

render_regular_section

Render any other section.

render_parameter

Render a single NumpyDoc Parameter as Markdown.

render_parameter_section

Convert parsed parameters into final markdown we want to render.

report_errors_in_docstring

Warn for docstring errors.

to_pure_markdown

Convert a hybrid NumpyDoc/MyST docstring to pure Markdown.

replace_output_files_title

Replace “Output Files” section name with “Other Parameters”, as a parsing hack.

Data#

_PARAMETERS_SECTIONS

_REGULAR_SECTIONS

_OTHER_PARAMETERS

Regular expression to check if the “Other Parameters” section has been used.

_OUTPUT_SECTION_TITLE

Regular expression to extract the “Output Files” section title in rST format.

Parser

API#

dev.docs.docstrings._PARAMETERS_SECTIONS: Final[tuple[str, ...]]#

(‘Parameters’, ‘Returns’, ‘Yields’, ‘Receives’, ‘Other Parameters’, ‘Raises’, ‘Warns’, ‘Attributes’)

dev.docs.docstrings._REGULAR_SECTIONS: Final[tuple[str, ...]]#

(‘Warnings’, ‘Notes’, ‘References’, ‘Examples’)

dev.docs.docstrings._OTHER_PARAMETERS#

‘compile(…)’

Regular expression to check if the “Other Parameters” section has been used.

We cannot allow users to include “Other Parameters” section, because we hijack it to easily render our “Output Files” section without having to patch the NumpyDoc parser.

Matches text that looks like:

Other Parameters
----------------
dev.docs.docstrings._OUTPUT_SECTION_TITLE#

‘compile(…)’

Regular expression to extract the “Output Files” section title in rST format.

We use this to pretend the “Output Files” section title is actually “Other Parameters” before passing it to the NumpyDoc parser.

Matches text that looks like:

{before}
{padding}Other Parameters
----------------

{after}
dev.docs.docstrings.render_see_also(
see_also: dev.docs.types.SingleSeeAlso,
) → str#

Render a single NumpyDoc “See Also” reference.

dev.docs.docstrings.render_see_also_section(
section: dev.docs.types.SeeAlsoSection,
) → str#

Render the full “See Also” section from parsed output of NumpyDoc.

dev.docs.docstrings.render_regular_section(
section: dev.docs.types.RegularSection,
) → str#

Render any other section.

dev.docs.docstrings.render_parameter(
parameter: numpydoc.docscrape.Parameter,
) → str#

Render a single NumpyDoc Parameter as Markdown.

dev.docs.docstrings.render_parameter_section(
section: list[numpydoc.docscrape.Parameter],
) → str#

Convert parsed parameters into final markdown we want to render.

dev.docs.docstrings.report_errors_in_docstring(
doc: str,
document: docutils.nodes.document,
) → None#

Warn for docstring errors.

dev.docs.docstrings.to_pure_markdown(
doc: str,
use_other_params_as_outputs: bool = True,
) → str#

Convert a hybrid NumpyDoc/MyST docstring to pure Markdown.

dev.docs.docstrings.replace_output_files_title(
doc: str,
source: str | None,
) → str#

Replace “Output Files” section name with “Other Parameters”, as a parsing hack.

As a side effect, this means we cannot allow users to use the “Other Parameters” section.

Parameters#

  • doc (str): The docstring to cleanup.

  • source (str): A string describing the source file, if available. Otherwise ‘[UNKNOWN]’ will be printed.

Returns#

  • str (A docstring ready to hand to numpydoc.docscrape.NumpyDocString.)

class dev.docs.docstrings.MystNumpyDocHybridParser#

Bases: myst_parser.parsers.sphinx_.MystParser

Hybrid docstring. Use NumpyDoc style, but allow Markdown instead of rST.

parse(
inputstring: str,
document: docutils.nodes.document,
) → None#

Parse source text.

Parameters#

  • inputstring (str): The docstring to parse. Name intentionally chosen to match internal Sphinx usage.

  • document (nodes.document): The root docutils node to add AST elements to.

dev.docs.docstrings.Parser#

None

Contents