Install & Compatibility
Where this runs
tested against v0.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
napoleon
✓ # conf.py
extensions = ['sphinxcontrib.napoleon']
✗ from sphinxcontrib import 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.
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)
Debug
Known issues
breakingThe `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.fixUpdate 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.
affects: Sphinx > 1.2
breakingVersion 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`.fixUpgrade 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.
affects: 0.7 on Python 3.10+
gotchaNapoleon 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.fixChoose 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.
affects: All versions
gotchaOlder 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.fixEnsure 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.
affects: 0.1 - 0.4.3 (prior to fixes incorporated into Sphinx's napoleon extension)
Upgrade
Version history
0.7latest on PyPI · released Sep 23, 2018
Audit
Dependencies
SphinxrequiredNapoleon is a Sphinx extension and requires Sphinx to function.