Sphinx Napoleon Extension

0.7 · maintenance · verified Tue Apr 14

Sphinxcontrib-napoleon is a Sphinx extension that acts as a pre-processor, enabling Sphinx to parse and convert both NumPy and Google style docstrings into reStructuredText. This allows developers to write more legible and less verbose docstrings in their Python code. The standalone `sphinxcontrib-napoleon` package is currently at version 0.7, with its last release in 2018. While this package is maintained for compatibility with older Sphinx versions (<=1.2), its core functionality has been integrated directly into Sphinx as `sphinx.ext.napoleon` since Sphinx 1.3, making the `sphinx.ext.napoleon` path the modern standard for newer Sphinx projects.

Warnings

breaking The `sphinxcontrib-napoleon` package is intended for Sphinx versions up to 1.2. For Sphinx 1.3 and newer, Napoleon's functionality is included directly within Sphinx as `sphinx.ext.napoleon`. While `sphinxcontrib-napoleon` might still function with newer Sphinx versions, using `sphinx.ext.napoleon` is the official and recommended path.
Fix: Update your `conf.py` to use `'sphinx.ext.napoleon'` instead of `'sphinxcontrib.napoleon'` in the `extensions` list when using Sphinx 1.3 or higher. You may also be able to uninstall the `sphinxcontrib-napoleon` package if your Sphinx version is recent enough.
breaking Version 0.7 of `sphinxcontrib-napoleon` (last updated 2018) is incompatible with Python 3.10+ due to a breaking change in Python 3.10 that moved `Callable` from the `collections` module to `collections.abc`. This results in an `ImportError`.
Fix: Upgrade to a newer version of Sphinx (1.3+) and use the built-in `sphinx.ext.napoleon` extension, which has addressed this compatibility issue. If you must use `sphinxcontrib-napoleon` 0.7, you would need to manually patch the source or use an environment with Python < 3.10.
gotcha Napoleon supports both Google and NumPy style docstrings, but mixing them within a single project is strongly discouraged. While both styles are parsed, inconsistent styling can lead to less readable documentation and potential formatting quirks.
Fix: Choose either Google style or NumPy style docstrings for your project and adhere to it consistently throughout your codebase for optimal readability and consistent documentation output.
gotcha Older versions of Napoleon (prior to fixes in Sphinx) had issues correctly parsing `*args` and `**kwargs` in Google-style docstrings, leading to these parameters not being properly included in the generated documentation.
Fix: Ensure you are using a recent version of Sphinx (with its bundled `sphinx.ext.napoleon`) or `sphinxcontrib-napoleon` version 0.4.4 or higher, which included improvements for `*args` and `**kwargs` handling.

Install

pip install sphinxcontrib-napoleon Install `sphinxcontrib-napoleon`

Imports

napoleon
```
# conf.py
extensions = ['sphinxcontrib.napoleon']
```
Napoleon is enabled as a Sphinx extension by adding its name to the 'extensions' list in Sphinx's conf.py, not via a direct Python import statement. For Sphinx 1.3+ users, the correct path is 'sphinx.ext.napoleon'.
napoleon
```
# conf.py
extensions = ['sphinx.ext.napoleon']
```
For Sphinx 1.3 and newer, the Napoleon extension is bundled directly with Sphinx. Using 'sphinx.ext.napoleon' is the recommended approach. The 'sphinxcontrib.napoleon' package specifically targets Sphinx versions <= 1.2.

Quickstart

To quickly integrate Napoleon, install the package, then enable it in your Sphinx project's `conf.py` by adding `'sphinx.ext.napoleon'` (or `'sphinxcontrib.napoleon'` for older Sphinx versions) to the `extensions` list. Ensure `sphinx.ext.autodoc` is also enabled. After configuration, use `sphinx-apidoc` to generate RST files from your Python source and then `make html` (or `sphinx-build`) to build the documentation.

# 1. Install sphinxcontrib-napoleon (if using Sphinx <= 1.2, or for older projects)
# pip install sphinxcontrib-napoleon

# 2. In your Sphinx project's conf.py file:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

# Add 'sphinx.ext.autodoc' to ensure docstrings are processed
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon' # Use 'sphinxcontrib.napoleon' for Sphinx <= 1.2
]

# Optional: Configure napoleon settings (defaults shown)
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = False
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_use_keyword = True
napoleon_custom_sections = None

# 3. Generate API documentation (run from your project root or docs directory):
# sphinx-apidoc -f -o docs/source your_project_module_path
# make html (or sphinx-build -b html docs/source docs/build/html)

view raw JSON →