NumPy Docstring Renderer

A utility that previews NumPy-style docstrings by converting them into reStructuredText and optionally writing them to disk using the target package.

Capabilities

Render callables

• Rendering a function that documents parameters and a return value in NumPy style returns RST that includes the Parameters and Returns sections with dedented entries for each documented name. @test
• Rendering a class with an Attributes section preserves each attribute block and formats them under the Attributes heading in the RST output. @test

Render raw text

• Rendering a raw NumPy-style docstring string that contains See Also and Examples sections returns RST that includes those headings, preserves code block indentation, and keeps See Also references on separate lines. @test

Save output

• Saving rendered RST to an existing file path overwrites previous content and leaves the serialized RST unchanged when read back. @test

Implementation

@generates

API

from typing import Any, Mapping

def render_docstring(obj: Any, *, config: Mapping[str, object] | None = None) -> str:
    """Render the NumPy-format docstring for the given callable, class, or module into RST."""

def render_docstring_text(doc: str, *, name: str | None = None, config: Mapping[str, object] | None = None) -> str:
    """Render a raw NumPy-style docstring string into RST, optionally using a display name."""

def save_rendered(rst: str, path: str) -> None:
    """Write rendered RST to the given file path, overwriting existing content."""

Dependencies { .dependencies }

numpydoc { .dependency }

Parses NumPy-format docstrings and renders them into reStructuredText suitable for Sphinx and CLI previews.