Docstring QA Toolkit

A lightweight helper module that wraps the dependency's command-line tools to render NumPy-style docstrings, validate a specific object, and lint multiple files.

Capabilities

Render an object docstring

• Given an import path to an object with a well-formed NumPy-style docstring, returns rendered reStructuredText that includes the object's name and a Parameters section. @test
• When rendering fails because the object cannot be imported, raises a RuntimeError that includes the exit status from the underlying CLI. @test

Validate a documented object

• Validating an object whose docstring omits one documented parameter returns a list that includes the corresponding validation code string. @test
• Validating an object with a complete docstring returns an empty list and completes without an exception. @test

Lint a set of files

• Linting two files where one is clean and one has violations returns a mapping with an empty list for the clean file and at least one lint code string for the other. @test
• Linting a single clean file returns an empty mapping and a zero exit status. @test

Implementation

Wrap the dependency's CLI entrypoints for rendering, validation, and linting rather than reimplementing docstring parsing. Support forwarding an optional config path to render and validate, and optional ignore patterns when linting.

@generates

API

from typing import Dict, List, Optional

def render_docstring(import_path: str, config: Optional[Dict[str, str]] = None) -> str:
    """Render RST for the given import path using the dependency's CLI."""


def validate_docstring(import_path: str, checks: Optional[List[str]] = None) -> List[str]:
    """Run validation for the given import path and return failing code strings in order."""


def lint_files(paths: List[str], ignores: Optional[List[str]] = None) -> Dict[str, List[str]]:
    """Run linting for the provided file paths and return failing code strings per file."""

Dependencies { .dependencies }

numpydoc { .dependency }

Provides CLI utilities for rendering docstrings, validating a single object, and linting files.