Signature-Aware Docstring Renderer

Build a CLI that renders a Python object's NumPy-style docstring to reStructuredText while supporting custom templates and fallback signature inference.

Capabilities

Fallback signature inference

• When the target callable lacks a runtime signature but its docstring lists value and scale=1.0 parameters, the rendered output includes a (value, scale=1.0) signature derived from the docstring metadata. @test

Template override

• When a custom Jinja template path is provided, the renderer uses it and the output contains the template-specific marker text Custom Docstring Layout. @test

Clean text signatures

• When the target exposes __text_signature__="(self, value, /, *, scale)", the rendered signature omits positional-only prefix clutter and shows (self, value, *, scale) without duplicated module prefixes. @test

File output

• Given an --output path, the CLI writes the rendered docstring to that file and returns the path; parent directories are created if they do not exist. @test

Implementation

@generates

API

def render_docstring(target: str, template_path: str | None = None, enable_inference: bool = False) -> str:
    """Render the target object's docstring to reStructuredText using an optional custom template."""


def render_to_file(target: str, output_path: str, template_path: str | None = None, enable_inference: bool = False) -> str:
    """Render the target docstring and write it to output_path, returning the written path."""


def main(argv: list[str] | None = None) -> int:
    """CLI entrypoint accepting --target, --template, --output, and --infer-signature flags."""

Dependencies { .dependencies }

numpydoc { .dependency }

Parses NumPy-style docstrings, infers call signatures when inspection fails, and renders reStructuredText with customizable templates.