numpydoc

Warnings

• breaking numpydoc version 1.10.0 and later require Python 3.10+. Support for Python 3.9 and earlier has been dropped. Version 1.6.0 introduced a requirement for Python 3.8+.
  Fix: Upgrade your Python environment to 3.10 or newer. If you need to use an older Python, pin numpydoc to a compatible version (e.g., `<1.10.0` for Python 3.9).
• breaking numpydoc version 1.10.0 and later require Sphinx 6+. Earlier versions (e.g., 1.6.0) required Sphinx 5+, and even older versions had lower requirements (e.g., 1.2.1 required Sphinx 1.8+).
  Fix: Ensure your Sphinx installation meets the minimum version requirement for your numpydoc version. Upgrade Sphinx to 6.0 or newer for numpydoc 1.10.0.
• deprecated The `numpydoc_edit_link` configuration option was deprecated in version 1.3rc1 and subsequently removed. Its functionality for inserting an edit link is now handled via HTML templates.
  Fix: Remove `numpydoc_edit_link` from your `conf.py`. If you need an edit link, configure it directly within your Sphinx HTML theme templates.
• gotcha numpydoc introduced support for configuration via `pyproject.toml` in version 1.6.0, with enhancements (e.g., `exclude_files` for validation) in 1.10.0. While `conf.py` remains the primary config, users transitioning or with complex build systems should be aware of `pyproject.toml` options.
  Fix: Review numpydoc's documentation for `pyproject.toml` configuration options, particularly if you manage project metadata or build settings via `pyproject.toml`.
• gotcha The command-line interfaces (CLIs) for numpydoc were unified in version 1.8.0. If you were using separate or older CLI commands, they might have changed.
  Fix: Consult the numpydoc documentation for the updated CLI usage. Adjust any scripts or automation that invoke numpydoc's command-line tools.
• gotcha CSS styling for definition lists changed significantly in numpydoc versions less than 0.8 and Sphinx versions less than 2.0. This can cause rendering issues, especially with themes like `sphinx-rtd-theme`.
  Fix: If experiencing rendering issues, particularly with definition lists, ensure both numpydoc and Sphinx are updated to recent versions. Custom CSS might be required for older setups.

Install

• pip install numpydoc Install latest version

Imports

• numpydoc

  # In your Sphinx conf.py file:
  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.autosummary', # Automatically loaded by numpydoc
      'numpydoc'
  ]

  numpydoc is a Sphinx extension, not a Python library imported for direct application use. It's added to the 'extensions' list in Sphinx's conf.py to enable its features.

Quickstart

To use numpydoc, you primarily need to add 'numpydoc' to the `extensions` list in your Sphinx `conf.py` file. This enables NumPy-style docstring parsing. You typically use it alongside `sphinx.ext.autodoc` for automatic documentation generation. Other common extensions like `sphinx.ext.autosummary` are often used and are automatically loaded by numpydoc.

# conf.py (in your Sphinx project's docs/source directory)

import os
import sys
# If your project is a package, add its path to sys.path
# sys.path.insert(0, os.path.abspath('../../src')) # Example for a 'src' directory two levels up

project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'numpydoc'
]

templates_path = ['_templates']
exclude_patterns = []

html_theme = 'alabaster'
html_static_path = ['_static']

# Numpydoc specific configuration (optional, set as needed)
numpydoc_show_class_members = False
numpydoc_class_members_toctree = False
numpydoc_xref_param_type = True

# To enable validation of docstrings during build
numpydoc_validation_checks = {"all"}