or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tools.mddocstring-parsing.mdhooks.mdindex.mdsphinx-extension.mdvalidation.md
tile.json

tessl/pypi-numpydoc

Sphinx extension to support docstrings in Numpy format

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/numpydoc@1.9.x

To install, run

npx @tessl/cli install tessl/pypi-numpydoc@1.9.0

index.mddocs/

numpydoc

numpydoc is a Sphinx extension for handling docstrings in NumPy format. It provides comprehensive tools for parsing, validating, and rendering NumPy-style docstrings, along with command-line utilities and Git hooks for automated docstring validation.

Package Information

  • Package: numpydoc
  • Version: 1.9.0
  • Python: 3.9+
  • Install: pip install numpydoc
  • Repository: https://github.com/numpy/numpydoc

Dependencies

  • Required: sphinx>=6, tomli>=1.1.0 (Python <3.11)
  • Development: pytest, matplotlib, pre-commit

Core Imports

# Main Sphinx extension setup
from numpydoc import setup

# CLI functionality  
from numpydoc.cli import main, get_parser, render_object, validate_object

# Core Sphinx extension
from numpydoc.numpydoc import (
    setup, mangle_docstrings, mangle_signature, 
    NumpyPythonDomain, NumpyCDomain
)

# Docstring parsing
from numpydoc.docscrape import (
    NumpyDocString, FunctionDoc, ClassDoc, ObjDoc, 
    get_doc_object, Reader
)

# Sphinx integration
from numpydoc.docscrape_sphinx import (
    SphinxDocString, SphinxFunctionDoc, SphinxClassDoc, 
    SphinxObjDoc, get_doc_object
)

# Validation
from numpydoc.validate import Validator, validate

# Cross-referencing
from numpydoc.xref import make_xref

# Git hooks
from numpydoc.hooks.validate_docstrings import run_hook, parse_config

Basic Usage

Sphinx Extension Setup

Add numpydoc to your Sphinx configuration:

# conf.py
extensions = ['numpydoc']

# Configuration options
numpydoc_use_plots = False
numpydoc_show_class_members = True
numpydoc_validation_checks = {'all', 'GL08'}

Command Line Usage

# Render docstring to reStructuredText
numpydoc render numpy.array

# Validate single object docstring  
numpydoc validate numpy.mean

# Validate files using AST parsing
numpydoc lint src/mymodule.py

Capabilities

Sphinx Extension

Core Sphinx extension functionality for processing NumPy-style docstrings during documentation builds.

def setup(app, *args, **kwargs):
    """Main Sphinx extension setup function."""
    ...

def mangle_docstrings(app, what, name, obj, options, lines):
    """Process docstrings during Sphinx build."""
    ...

Docstring Parsing

Comprehensive parsing capabilities for NumPy docstring format with section handling and dictionary-like access.

class NumpyDocString(Mapping):
    """Base docstring parser with dictionary-like interface."""
    
    def __getitem__(self, key: str) -> List[str]:
        """Access docstring sections by name."""
        ...

def get_doc_object(obj, what=None, doc=None, config=None, **kwargs):
    """Factory function for creating appropriate docstring parsers."""
    ...

Validation

Extensive validation rules with configurable error codes for ensuring docstring quality and consistency.

class Validator:
    """Main docstring validation class with extensive validation methods."""
    

def validate(obj_name, validator_cls=None, **validator_kwargs):
    """Validate docstring for given object name."""
    ...

CLI Tools

Command-line interface for rendering and validation with support for multiple output formats.

def main(argv=None) -> int:
    """CLI entry point, returns exit code."""
    ...

def render_object(import_path: str, config=None):
    """Test docstring rendering for object."""
    ...

def validate_object(import_path: str):
    """Run validation for object."""
    ...

Git Hooks

Pre-commit integration for automated docstring validation with configurable rules and project detection.

def run_hook(files, config=None, ignore=None):
    """Main hook function for pre-commit validation."""
    ...

def parse_config(dir_path=None):
    """Parse validation config from pyproject.toml/setup.cfg."""
    ...

Package Constants

__version__: str = "1.9.0"
"""Package version string."""

HASH_LEN: int = 12
"""Length for reference hash generation."""

DEDUPLICATION_TAG: str = "<!-- numpydoc_validation -->"
"""Tag for processed docstring identification."""

DEFAULT_LINKS: Dict[str, str]
"""
Default cross-reference mappings for common Python types.

Dictionary mapping type names to Sphinx cross-reference roles for
automatic linking of parameter and return types in documentation.
Includes standard Python types like 'str', 'int', 'list', 'dict', etc.
"""

Configuration Options

numpydoc provides 13 Sphinx configuration values for customizing behavior:

  • numpydoc_use_plots - Enable plot directive processing
  • numpydoc_show_class_members - Show class members in documentation
  • numpydoc_show_inherited_class_members - Show inherited members
  • numpydoc_class_members_toctree - Generate TOC for class members
  • numpydoc_citation_re - Regular expression for citation detection
  • numpydoc_attributes_as_param_list - Format attributes as parameters
  • numpydoc_xref_param_type - Enable parameter type cross-references
  • numpydoc_xref_aliases - Custom type alias mappings
  • numpydoc_xref_ignore - Types to ignore for cross-referencing
  • numpydoc_validation_checks - Validation rules to apply
  • numpydoc_validation_exclude - Objects to exclude from validation
  • numpydoc_validation_overrides - Override validation rules per object

Sub-Documentation