sphinxcontrib-napoleon

What it is and what it does

sphinxcontrib-napoleon is a Sphinx extension that preprocesses docstrings written in Google or NumPy style and converts them to reStructuredText before Sphinx parses them. This allows developers to write cleaner, more readable docstrings without the verbose reStructuredText markup (e.g., `:param name: description` becomes `Args: name: description`), while still generating properly formatted API documentation.

The extension integrates into Sphinx's autodoc workflow and automatically recognizes specially formatted sections like Args, Returns, Raises, Examples, and many others. It supports both Google-style (indentation-based) and NumPy-style (underline-based) docstring formats. However, this package is now obsolete: Sphinx has included Napoleon as a built-in extension since version 1.3, making this separate package unnecessary for modern projects.

Use it for:

• Migrating from verbose reStructuredText docstrings to Google-style docstrings in a Sphinx project using Sphinx <= 1.2.
• Maintaining legacy documentation builds that depend on sphinxcontrib-napoleon and cannot upgrade to modern Sphinx.
• Converting NumPy-style docstrings to reStructuredText for API documentation generation in older projects.
• Enabling consistent docstring parsing across Google and NumPy styles in a single Sphinx build.

Worth the install?

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

A Sphinx extension that converts Google and NumPy style docstrings into reStructuredText, making documentation source code more readable during the build process.

No. This package is abandoned (last release 2018-09-23) and superseded by the built-in sphinx.ext.napoleon in Sphinx 1.3+. Unless you are maintaining legacy documentation on Sphinx <= 1.2, use the built-in extension instead. For modern Sphinx, simply add 'sphinx.ext.napoleon' to your extensions list.

Install

sphinxcontrib-napoleon on PyPI

pip install sphinxcontrib-napoleon

uv add sphinxcontrib-napoleon

poetry add sphinxcontrib-napoleon

Installing sphinxcontrib-napoleon

Before you install

Low friction to install with only two runtime dependencies (six and pockets). However, the package is abandoned—last release was 2018-09-23. Since Sphinx 1.3, Napoleon is built into Sphinx itself, making this backport unnecessary for modern projects.

License in practice

BSD license is permissive and poses no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install sphinxcontrib-napoleon

# In conf.py:
extensions = ['sphinxcontrib.napoleon']

# Then write docstrings in Google or NumPy style; Sphinx autodoc will parse them automatically.

Sphinx must be installed and configured; this extension is primarily useful for Sphinx versions <= 1.2 (for newer Sphinx, use the built-in sphinx.ext.napoleon instead).

Verify before relying

• Whether the package remains compatible with modern Python versions or recent Sphinx releases, given its 2018 final release.
• Whether the built-in sphinx.ext.napoleon in current Sphinx versions has feature parity or if edge cases still require this backport.

Package facts

Evidence: sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl

Tags

More Utilities packages