Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use type and default option to confval in napoleon docs #13094

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
+41 −15
Open

Use type and default option to confval in napoleon docs #13094

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5dccd13
update the default value of `napoleon_attr_annotations`
Snoopy1866 Nov 1, 2024
9c05fe7
Merge branch 'master' into docs-usage-extension-napoleon-napoleon_att…
Snoopy1866 Nov 5, 2024
b9e1baf
Use type and default option to confval
Snoopy1866 Nov 5, 2024
fa454aa
Use double backticks
Snoopy1866 Nov 5, 2024
bb35cdc
Use interpreted text role `code-py`
Snoopy1866 Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 41 additions & 15 deletions doc/usage/extensions/napoleon.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,21 +301,27 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

.. confval:: napoleon_google_docstring
:type: bool
:default: True

True to parse `Google style`_ docstrings. False to disable support
for Google style docstrings. *Defaults to True.*
for Google style docstrings.

.. confval:: napoleon_numpy_docstring
:type: bool
:default: True

True to parse `NumPy style`_ docstrings. False to disable support
for NumPy style docstrings. *Defaults to True.*
for NumPy style docstrings.

.. confval:: napoleon_include_init_with_doc
:type: bool
:default: False

True to list ``__init___`` docstrings separately from the class
docstring. False to fall back to Sphinx's default behavior, which
considers the ``__init___`` docstring as part of the class
documentation. *Defaults to False.*
documentation.

**If True**::

Expand All @@ -328,10 +334,11 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
# This will NOT be included in the docs

.. confval:: napoleon_include_private_with_doc
:type: bool
:default: False

True to include private members (like ``_membername``) with docstrings
in the documentation. False to fall back to Sphinx's default behavior.
*Defaults to False.*

**If True**::

Expand All @@ -346,10 +353,12 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
pass

.. confval:: napoleon_include_special_with_doc
:type: bool
:default: True

True to include special members (like ``__membername__``) with
docstrings in the documentation. False to fall back to Sphinx's
default behavior. *Defaults to True.*
default behavior.

**If True**::

Expand All @@ -364,11 +373,13 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
return unicode(self.__class__.__name__)

.. confval:: napoleon_use_admonition_for_examples
:type: bool
:default: False

True to use the ``.. admonition::`` directive for the **Example** and
**Examples** sections. False to use the ``.. rubric::`` directive
instead. One may look better than the other depending on what HTML
theme is used. *Defaults to False.*
theme is used.

This `NumPy style`_ snippet will be converted as follows::

Expand All @@ -389,9 +400,11 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
This is just a quick example

.. confval:: napoleon_use_admonition_for_notes
:type: bool
:default: False

True to use the ``.. admonition::`` directive for **Notes** sections.
False to use the ``.. rubric::`` directive instead. *Defaults to False.*
False to use the ``.. rubric::`` directive instead.

.. note:: The singular **Note** section will always be converted to a
``.. note::`` directive.
Expand All @@ -401,19 +414,22 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
:confval:`napoleon_use_admonition_for_examples`

.. confval:: napoleon_use_admonition_for_references
:type: bool
:default: False

True to use the ``.. admonition::`` directive for **References**
sections. False to use the ``.. rubric::`` directive instead.
*Defaults to False.*

.. seealso::

:confval:`napoleon_use_admonition_for_examples`

.. confval:: napoleon_use_ivar
:type: bool
:default: False

True to use the ``:ivar:`` role for instance variables. False to use
the ``.. attribute::`` directive instead. *Defaults to False.*
the ``.. attribute::`` directive instead.

This `NumPy style`_ snippet will be converted as follows::

Expand All @@ -436,10 +452,11 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
:type: int

.. confval:: napoleon_use_param
:type: bool
:default: True

True to use a ``:param:`` role for each function parameter. False to
use a single ``:parameters:`` role for all the parameters.
*Defaults to True.*

This `NumPy style`_ snippet will be converted as follows::

Expand All @@ -465,11 +482,12 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
Description of `arg2`, defaults to 0

.. confval:: napoleon_use_keyword
:type: bool
:default: True

True to use a ``:keyword:`` role for each function keyword argument.
False to use a single ``:keyword arguments:`` role for all the
keywords.
*Defaults to True.*

This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
``:keyword:`` and ``:param:`` will not be treated the same way - there will
Expand All @@ -481,9 +499,11 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
:confval:`napoleon_use_param`

.. confval:: napoleon_use_rtype
:type: bool
:default: True

True to use the ``:rtype:`` role for the return type. False to output
the return type inline with the description. *Defaults to True.*
the return type inline with the description.

This `NumPy style`_ snippet will be converted as follows::

Expand All @@ -502,19 +522,22 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
:returns: *bool* -- True if successful, False otherwise

.. confval:: napoleon_preprocess_types
:type: bool
:default: False

True to convert the type definitions in the docstrings as references.
Defaults to *False*.

.. versionadded:: 3.2.1
.. versionchanged:: 3.5

Do preprocess the Google style docstrings also.

.. confval:: napoleon_type_aliases
:type: `Optional[dict[str, str]]`
:default: `None`

A mapping to translate type names to other names or references. Works
only when ``napoleon_use_param = True``. *Defaults to None.*
only when ``napoleon_use_param = True``.

With::

Expand Down Expand Up @@ -542,6 +565,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
.. versionadded:: 3.2

.. confval:: napoleon_attr_annotations
:type: `bool`
Snoopy1866 marked this conversation as resolved.
Show resolved Hide resolved
:default: `True`

True to allow using :pep:`526` attributes annotations in classes.
If an attribute is documented in the docstring without a type and
Expand All @@ -550,9 +575,10 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::
.. versionadded:: 3.4

.. confval:: napoleon_custom_sections
:type: `Optional[Sequence[str | Sequence[str, str]]]`
Copy link
Contributor Author

@Snoopy1866 Snoopy1866 Nov 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it necessary to use Sequence instead of list or tuple here? And should I use the |, or nested Optional?

:default: `None`

Add a list of custom sections to include, expanding the list of parsed sections.
*Defaults to None.*

The entries can either be strings or tuples, depending on the intention:

Expand Down
Loading