{"id":6248,"library":"sphinxcontrib-napoleon","title":"Sphinx Napoleon Extension","description":"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.","status":"maintenance","version":"0.7","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/napoleon","tags":["Sphinx","documentation","docstrings","NumPy style","Google style"],"install":[{"cmd":"pip install sphinxcontrib-napoleon","lang":"bash","label":"Install `sphinxcontrib-napoleon`"}],"dependencies":[{"reason":"Napoleon is a Sphinx extension and requires Sphinx to function.","package":"Sphinx"}],"imports":[{"note":"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'.","wrong":"from sphinxcontrib import napoleon","symbol":"napoleon","correct":"# conf.py\nextensions = ['sphinxcontrib.napoleon']"},{"note":"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.","symbol":"napoleon","correct":"# conf.py\nextensions = ['sphinx.ext.napoleon']"}],"quickstart":{"code":"# 1. Install sphinxcontrib-napoleon (if using Sphinx <= 1.2, or for older projects)\n# pip install sphinxcontrib-napoleon\n\n# 2. In your Sphinx project's conf.py file:\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\n# Add 'sphinx.ext.autodoc' to ensure docstrings are processed\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon' # Use 'sphinxcontrib.napoleon' for Sphinx <= 1.2\n]\n\n# Optional: Configure napoleon settings (defaults shown)\nnapoleon_google_docstring = True\nnapoleon_numpy_docstring = True\nnapoleon_include_init_with_doc = False\nnapoleon_include_private_with_doc = False\nnapoleon_include_special_with_doc = False\nnapoleon_use_admonition_for_examples = False\nnapoleon_use_admonition_for_notes = False\nnapoleon_use_admonition_for_references = False\nnapoleon_use_ivar = False\nnapoleon_use_param = True\nnapoleon_use_rtype = True\nnapoleon_use_keyword = True\nnapoleon_custom_sections = None\n\n# 3. Generate API documentation (run from your project root or docs directory):\n# sphinx-apidoc -f -o docs/source your_project_module_path\n# make html (or sphinx-build -b html docs/source docs/build/html)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"Sphinx > 1.2"},{"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.","message":"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`.","severity":"breaking","affected_versions":"0.7 on Python 3.10+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.1 - 0.4.3 (prior to fixes incorporated into Sphinx's napoleon extension)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}