repository·master·Indexed 41 days ago
https://github.com/sphinx-contrib/napoleonA Sphinx extension that acts as a pre-processor to convert Google and NumPy style Python docstrings into standard reStructuredText. It supports various section headers such as Args, Returns, and Raises, and integrates with PEP 484 type annotations to allow cleaner docstrings.
Napoleon is a Sphinx extension that acts as a pre-processor. It parses Google and NumPy style docstrings and converts them into standard reStructuredText (rST) before Sphinx processes them.
This conversion happens during the Sphinx documentation build process and does not modify your actual source code files. Napoleon can interpret docstrings for modules, classes, attributes, methods, functions, and variables that are discovered by Sphinx autodoc.
Napoleon supports two distinct docstring styles. You should choose one and remain consistent throughout your project; do not mix them.
# Google style
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
# NumPy style
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return TrueTo use Napoleon to parse Google or NumPy style docstrings in your Sphinx documentation, follow these steps:
Install the extension via pip:
pip install sphinxcontrib-napoleonEnable the extension in your Sphinx conf.py file by adding 'sphinxcontrib.napoleon' to the extensions list.
Use sphinx-apidoc to generate your API documentation files from your source code.
$ pip install sphinxcontrib-napoleon
# In conf.py
extensions = ['sphinxcontrib.napoleon']
$ sphinx-apidoc -f -o docs/source projectdirNapoleon supports two primary docstring styles. You should choose one and remain consistent throughout your project; do not mix them.
Uses indentation to separate sections. It is more horizontally compact and is often preferred for short, simple docstrings.
def func(arg1, arg2):
"""Summary line.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return TrueUses underlines to separate sections. It requires more vertical space but is often easier to read for long, in-depth docstrings.
def func(arg1, arg2):
"""Summary line.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return Truedef func(arg1, arg2):
"""Summary line.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return TrueTo use Napoleon in your Sphinx documentation project, install the extension via pip and add it to your conf.py extensions list.
Note: If you are using Sphinx 1.3 or newer, Napoleon is already included in the Sphinx core as sphinx.ext.napoleon. Use sphinxcontrib-napoleon specifically for Sphinx versions <= 1.2.
$ pip install sphinxcontrib-napoleon# conf.py
# Add napoleon to the extensions list
extensions = ['sphinxcontrib.napoleon']This example demonstrates how to write Python docstrings using the NumPy style, which Napoleon can then parse into legible Sphinx documentation. The NumPy style typically uses underlined headers for sections like Parameters, Returns, and Raises.
def function_with_numpy_style(arg1, arg2):
"""
A brief description of the function.
Parameters
----------
arg1 : int
Description of arg1.
arg2 : str
Description of arg2.
Returns
-------
bool
Description of the return value.
"""
return TrueNapoleon supports using PEP 484 type annotations directly in your Python function signatures. When using type annotations, you can omit the types from the docstring sections (like Args or Returns), which helps keep docstrings clean and allows IDEs/type-checkers to perform static analysis.
Example (Google style with annotations):
def func(arg1: int, arg2: str) -> bool:
"""Summary line.
Extended description of function.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
"""
return Truedef func(arg1: int, arg2: str) -> bool:
"""Summary line.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
"""
return TrueNapoleon allows you to parse Python docstrings written in the Google style. This style uses indentation and specific section headers (like Args:, Returns:, etc.) to define documentation components, making them more readable in source code than standard reStructuredText.
To use this feature, ensure sphinxcontrib.napoleon is added to your Sphinx conf.py extensions list. You can then write docstrings following the Google format, and Napoleon will convert them into standard Sphinx documentation.
def function_with_google_style(arg1, arg2):
"""Example Google Style docstring.
Args:
arg1 (int): The first argument.
arg2 (str): The second argument.
Returns:
bool: True if successful, False otherwise.
"""
return TrueNapoleon recognizes several section headers within docstrings to convert them into structured documentation. The following headers are supported (including aliases):
Args, Arguments, Parameters, Other ParametersAttributesExample, ExamplesKeyword Args, Keyword ArgumentsMethodsNote, NotesReturn, ReturnsRaisesReferencesSee AlsoTodoWarning, Warnings, WarnsYield, YieldsOther (implied by general parsing)