{"id":3180,"library":"numpydoc","title":"numpydoc","description":"numpydoc is a Sphinx extension that enables the use of NumPy-style docstrings in Sphinx-generated documentation. It processes docstrings formatted according to the NumPy documentation format, adding functionality like autodoc integration and custom directives for functions and classes. The current version is 1.10.0, with releases occurring a few times a year.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/numpy/numpydoc/","tags":["sphinx","documentation","numpy","docstrings","extension"],"install":[{"cmd":"pip install numpydoc","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required runtime environment.","package":"Python","version":">=3.10"},{"reason":"Core documentation generator that numpydoc extends.","package":"Sphinx","version":">=6"}],"imports":[{"note":"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.","symbol":"numpydoc","correct":"# In your Sphinx conf.py file:\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary', # Automatically loaded by numpydoc\n    'numpydoc'\n]"}],"quickstart":{"code":"# conf.py (in your Sphinx project's docs/source directory)\n\nimport os\nimport sys\n# If your project is a package, add its path to sys.path\n# sys.path.insert(0, os.path.abspath('../../src')) # Example for a 'src' directory two levels up\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary',\n    'sphinx.ext.coverage',\n    'sphinx.ext.mathjax',\n    'sphinx.ext.viewcode',\n    'numpydoc'\n]\n\ntemplates_path = ['_templates']\nexclude_patterns = []\n\nhtml_theme = 'alabaster'\nhtml_static_path = ['_static']\n\n# Numpydoc specific configuration (optional, set as needed)\nnumpydoc_show_class_members = False\nnumpydoc_class_members_toctree = False\nnumpydoc_xref_param_type = True\n\n# To enable validation of docstrings during build\nnumpydoc_validation_checks = {\"all\"}\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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+.","severity":"breaking","affected_versions":">=1.10.0 (Python 3.10+); >=1.6.0 (Python 3.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.","message":"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+).","severity":"breaking","affected_versions":">=1.10.0 (Sphinx 6+); >=1.6.0 (Sphinx 5+)"},{"fix":"Remove `numpydoc_edit_link` from your `conf.py`. If you need an edit link, configure it directly within your Sphinx HTML theme templates.","message":"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.","severity":"deprecated","affected_versions":">=1.3.1"},{"fix":"Review numpydoc's documentation for `pyproject.toml` configuration options, particularly if you manage project metadata or build settings via `pyproject.toml`.","message":"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.","severity":"gotcha","affected_versions":">=1.6.0"},{"fix":"Consult the numpydoc documentation for the updated CLI usage. Adjust any scripts or automation that invoke numpydoc's command-line tools.","message":"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.","severity":"gotcha","affected_versions":">=1.8.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<0.8 (numpydoc) or <2.0 (Sphinx)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}