IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Use granular syntax highlighting for the Napoleon extension

Browse Source
This commit is contained in:
Adam Turner
2025-01-26 04:45:49 +00:00
parent 0bc8b4115d
commit 9a8eeac865
1 changed files with 74 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
doc/usage/extensions/napoleon.rst
View File

@@ -14,9 +14,9 @@
Overview
--------
.. highlight:: text
Are you tired of writing docstrings that look like this:
Are you tired of writing docstrings that look like this::
.. code-block:: rst
:param path: The path of the file to wrap
:type path: str
@@ -30,7 +30,9 @@ Are you tired of writing docstrings that look like this::
`reStructuredText`_ is great, but it creates visually dense, hard to read
:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
according to the `Google Python Style Guide`_::
according to the `Google Python Style Guide`_:
.. code-block:: text
Args:
path (str): The path of the file to wrap
@@ -66,14 +68,18 @@ Getting Started
~~~~~~~~~~~~~~~
1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
enable napoleon in the Sphinx ``conf.py`` file::
enable napoleon in the Sphinx ``conf.py`` file:
.. code-block:: python
# conf.py
# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']
2. Use ``sphinx-apidoc`` to build your API documentation::
2. Use ``sphinx-apidoc`` to build your API documentation:
.. code-block:: console
$ sphinx-apidoc -f -o docs/source projectdir
@@ -206,7 +212,9 @@ type checkers and IDEs can take advantage of them for static code
analysis. :pep:`484` was then extended by :pep:`526` which introduced
a similar way to annotate variables (and attributes).
Google style with Python 3 type annotations::
Google style with Python 3 type annotations:
.. code-block:: python
def func(arg1: int, arg2: str) -> bool:
"""Summary line.
@@ -236,7 +244,9 @@ Google style with Python 3 type annotations::
attr1: int
attr2: str
Google style with types in docstrings::
Google style with types in docstrings:
.. code-block:: python
def func(arg1, arg2):
"""Summary line.
@@ -263,19 +273,15 @@ Google style with types in docstrings::
attr2 (str): Description of attr2
"""
.. Note::
`Python 2/3 compatible annotations`_ aren't currently
supported by Sphinx and won't show up in the docs.
.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
Configuration
-------------
Listed below are all the settings used by napoleon and their default
values. These settings can be changed in the Sphinx ``conf.py`` file. Make
sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:
.. code-block:: python
# conf.py
@@ -326,7 +332,9 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
considers the ``__init___`` docstring as part of the class
documentation.
**If True**::
**If True**:
.. code-block:: python
def __init__(self):
"""
@@ -343,7 +351,9 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
True to include private members (like ``_membername``) with docstrings
in the documentation. False to fall back to Sphinx's default behavior.
**If True**::
**If True**:
.. code-block:: python
def _included(self):
"""
@@ -363,7 +373,9 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
docstrings in the documentation. False to fall back to Sphinx's
default behavior.
**If True**::
**If True**:
.. code-block:: python
def __str__(self):
"""
@@ -384,19 +396,25 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
instead. One may look better than the other depending on what HTML
theme is used.
This `NumPy style`_ snippet will be converted as follows::
This `NumPy style`_ snippet will be converted as follows:
.. code-block:: text
Example
-------
This is just a quick example
**If True**::
**If True**:
.. code-block:: rst
.. admonition:: Example
This is just a quick example
**If False**::
**If False**:
.. code-block:: rst
.. rubric:: Example
@@ -434,19 +452,25 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
True to use the ``:ivar:`` role for instance variables. False to use
the ``.. attribute::`` directive instead.
This `NumPy style`_ snippet will be converted as follows::
This `NumPy style`_ snippet will be converted as follows:
.. code-block:: text
Attributes
----------
attr1 : int
Description of `attr1`
**If True**::
**If True**:
.. code-block:: rst
:ivar attr1: Description of `attr1`
:vartype attr1: int
**If False**::
**If False**:
.. code-block:: rst
.. attribute:: attr1
@@ -461,7 +485,9 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
True to use a ``:param:`` role for each function parameter. False to
use a single ``:parameters:`` role for all the parameters.
This `NumPy style`_ snippet will be converted as follows::
This `NumPy style`_ snippet will be converted as follows:
.. code-block:: text
Parameters
----------
@@ -470,14 +496,18 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
arg2 : int, optional
Description of `arg2`, defaults to 0
**If True**::
**If True**:
.. code-block:: rst
:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: :class:`int`, *optional*
**If False**::
**If False**:
.. code-block:: rst
:parameters: * **arg1** (*str*) --
Description of `arg1`
@@ -508,19 +538,25 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
True to use the ``:rtype:`` role for the return type. False to output
the return type inline with the description.
This `NumPy style`_ snippet will be converted as follows::
This `NumPy style`_ snippet will be converted as follows:
.. code-block:: text
Returns
-------
bool
True if successful, False otherwise
**If True**::
**If True**:
.. code-block:: rst
:returns: True if successful, False otherwise
:rtype: bool
**If False**::
**If False**:
.. code-block:: rst
:returns: *bool* -- True if successful, False otherwise
@@ -542,14 +578,18 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
A mapping to translate type names to other names or references. Works
only when ``napoleon_use_param = True``.
With::
With:
.. code-block:: python
napoleon_type_aliases = {
"CustomType": "mypackage.CustomType",
"dict-like": ":term:`dict-like <mapping>`",
}
This `NumPy style`_ snippet::
This `NumPy style`_ snippet:
.. code-block:: text
Parameters
----------
@@ -558,7 +598,9 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
arg2 : dict-like
Description of `arg2`
becomes::
becomes:
.. code-block:: rst
:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType