numpydoc

What it is and what it does

numpydoc is a Sphinx extension that teaches Sphinx how to read and render docstrings written in NumPy's standardized documentation format. It parses sections like Parameters, Returns, Examples, and Notes, converting them into properly formatted HTML or other Sphinx output formats. The extension also provides specialized directives (np:function, np-c:function, etc.) for documenting NumPy-style code.

You install it as a dependency of your Sphinx documentation project, add it to your conf.py extensions list, and then write your code docstrings following the NumPy format guide. Sphinx will automatically use numpydoc to render them. It depends on Sphinx and tomli, making it a lightweight addition to existing documentation workflows.

Use it for:

• Documenting scientific Python libraries that follow NumPy's docstring conventions
• Converting existing NumPy-format docstrings into polished HTML API documentation via Sphinx
• Adding specialized code directives (np:function, np-c:function) to Sphinx projects documenting NumPy-adjacent code
• Enforcing consistent docstring structure across a team's scientific Python codebase
• Building documentation sites for projects that inherit or adopt NumPy's documentation standards

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that parses and renders docstrings written in NumPy documentation format, adding specialized directives for function and code documentation.

Yes. numpydoc is actively maintained, has no known vulnerabilities, installs with low friction, and is essential if you document scientific Python code using NumPy-format docstrings. The permissive BSD license poses no restrictions. Install it as part of your Sphinx setup if your project or team uses NumPy docstring conventions.

Install

numpydoc on PyPI

pip install numpydoc

uv add numpydoc

poetry add numpydoc

Installing numpydoc

Before you install

Low friction installation with a pure-Python wheel. Actively maintained with recent commits and no known vulnerabilities. Requires Python 3.10+ and Sphinx 6+.

License in practice

BSD 2-Clause permissive license allows use in commercial and private projects with minimal restrictions; only requires copyright notice and disclaimer in distributions.

Quickstart

pip install numpydoc

# In conf.py (Sphinx configuration):
extensions = ['numpydoc']

# Then write NumPy-format docstrings in your code

Requires Python 3.10+ and Sphinx 6+; must be configured in a Sphinx project's conf.py

Verify before relying

• Whether the extension handles all NumPy docstring edge cases or has known limitations with specific formats
• Performance characteristics when processing large codebases with many NumPy-format docstrings

Package facts

Evidence: numpydoc-1.10.0-py3-none-any.whl

Keywords: sphinx, numpy

Tags

More Documentation packages