From 5dccd1393967b7b9cf5ac45f92151b5891f37d48 Mon Sep 17 00:00:00 2001 From: Kun Jinkao <45487685+Snoopy1866@users.noreply.github.com> Date: Fri, 1 Nov 2024 11:42:12 +0800 Subject: [PATCH 1/4] update the default value of `napoleon_attr_annotations` --- doc/usage/extensions/napoleon.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 4b077defe97..13acb300ad2 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -546,6 +546,7 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: True to allow using :pep:`526` attributes annotations in classes. If an attribute is documented in the docstring without a type and has an annotation in the class body, that type is used. + *Defaults to True.* .. versionadded:: 3.4 From b9e1baf4bb0cdec59b42f597aecc065566ca56bd Mon Sep 17 00:00:00 2001 From: Kun Jinkao <45487685+Snoopy1866@users.noreply.github.com> Date: Tue, 5 Nov 2024 10:46:14 +0800 Subject: [PATCH 2/4] Use type and default option to confval --- doc/usage/extensions/napoleon.rst | 57 ++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 16 deletions(-) diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 13acb300ad2..8630484b5aa 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -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**:: @@ -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**:: @@ -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**:: @@ -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:: @@ -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. @@ -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:: @@ -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:: @@ -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 @@ -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:: @@ -502,9 +522,10 @@ 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 @@ -512,9 +533,11 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: 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:: @@ -542,18 +565,20 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: .. versionadded:: 3.2 .. confval:: napoleon_attr_annotations + :type: `bool` + :default: `True` True to allow using :pep:`526` attributes annotations in classes. If an attribute is documented in the docstring without a type and has an annotation in the class body, that type is used. - *Defaults to True.* .. versionadded:: 3.4 .. confval:: napoleon_custom_sections + :type: `Optional[Sequence[str | Sequence[str, str]]]` + :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: From fa454aaaf2ae2ae13aa1fc937d48c498ecd0707f Mon Sep 17 00:00:00 2001 From: Kun Jinkao <45487685+Snoopy1866@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:16:33 +0800 Subject: [PATCH 3/4] Use double backticks --- doc/usage/extensions/napoleon.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 8630484b5aa..89c1c7c9e4d 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -533,8 +533,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: Do preprocess the Google style docstrings also. .. confval:: napoleon_type_aliases - :type: `Optional[dict[str, str]]` - :default: `None` + :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``. @@ -565,8 +565,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: .. versionadded:: 3.2 .. confval:: napoleon_attr_annotations - :type: `bool` - :default: `True` + :type: ``bool`` + :default: ``True`` True to allow using :pep:`526` attributes annotations in classes. If an attribute is documented in the docstring without a type and @@ -575,8 +575,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: .. versionadded:: 3.4 .. confval:: napoleon_custom_sections - :type: `Optional[Sequence[str | Sequence[str, str]]]` - :default: `None` + :type: ``Optional[Sequence[str | Sequence[str, str]]]`` + :default: ``None`` Add a list of custom sections to include, expanding the list of parsed sections. From bb35cdc2b0d6fb49335c817318d0425e3a3abe16 Mon Sep 17 00:00:00 2001 From: Kun Jinkao <45487685+Snoopy1866@users.noreply.github.com> Date: Tue, 5 Nov 2024 20:07:43 +0800 Subject: [PATCH 4/4] Use interpreted text role `code-py` --- doc/usage/extensions/napoleon.rst | 64 +++++++++++++++---------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 89c1c7c9e4d..f0177b23b49 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -301,22 +301,22 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`True` True to parse `Google style`_ docstrings. False to disable support for Google style docstrings. .. confval:: napoleon_numpy_docstring - :type: bool - :default: True + :type: :code-py:`bool` + :default: :code-py:`True` True to parse `NumPy style`_ docstrings. False to disable support for NumPy style docstrings. .. confval:: napoleon_include_init_with_doc - :type: bool - :default: False + :type: :code-py:`bool` + :default: :code-py:`False` True to list ``__init___`` docstrings separately from the class docstring. False to fall back to Sphinx's default behavior, which @@ -334,8 +334,8 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`False` True to include private members (like ``_membername``) with docstrings in the documentation. False to fall back to Sphinx's default behavior. @@ -353,8 +353,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: pass .. confval:: napoleon_include_special_with_doc - :type: bool - :default: True + :type: :code-py:`bool` + :default: :code-py:`True` True to include special members (like ``__membername__``) with docstrings in the documentation. False to fall back to Sphinx's @@ -373,8 +373,8 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`False` True to use the ``.. admonition::`` directive for the **Example** and **Examples** sections. False to use the ``.. rubric::`` directive @@ -400,8 +400,8 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`False` True to use the ``.. admonition::`` directive for **Notes** sections. False to use the ``.. rubric::`` directive instead. @@ -414,8 +414,8 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`False` True to use the ``.. admonition::`` directive for **References** sections. False to use the ``.. rubric::`` directive instead. @@ -425,8 +425,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: :confval:`napoleon_use_admonition_for_examples` .. confval:: napoleon_use_ivar - :type: bool - :default: False + :type: :code-py:`bool` + :default: :code-py:`False` True to use the ``:ivar:`` role for instance variables. False to use the ``.. attribute::`` directive instead. @@ -452,8 +452,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: :type: int .. confval:: napoleon_use_param - :type: bool - :default: True + :type: :code-py:`bool` + :default: :code-py:`True` True to use a ``:param:`` role for each function parameter. False to use a single ``:parameters:`` role for all the parameters. @@ -482,8 +482,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: Description of `arg2`, defaults to 0 .. confval:: napoleon_use_keyword - :type: bool - :default: True + :type: :code-py:`bool` + :default: :code-py:`True` True to use a ``:keyword:`` role for each function keyword argument. False to use a single ``:keyword arguments:`` role for all the @@ -499,8 +499,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: :confval:`napoleon_use_param` .. confval:: napoleon_use_rtype - :type: bool - :default: True + :type: :code-py:`bool` + :default: :code-py:`True` True to use the ``:rtype:`` role for the return type. False to output the return type inline with the description. @@ -522,8 +522,8 @@ 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 + :type: :code-py:`bool` + :default: :code-py:`False` True to convert the type definitions in the docstrings as references. @@ -533,8 +533,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: Do preprocess the Google style docstrings also. .. confval:: napoleon_type_aliases - :type: ``Optional[dict[str, str]]`` - :default: ``None`` + :type: :code-py:`Optional[dict[str, str]]` + :default: :code-py:`None` A mapping to translate type names to other names or references. Works only when ``napoleon_use_param = True``. @@ -565,8 +565,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: .. versionadded:: 3.2 .. confval:: napoleon_attr_annotations - :type: ``bool`` - :default: ``True`` + :type: :code-py:`bool` + :default: :code-py:`True` True to allow using :pep:`526` attributes annotations in classes. If an attribute is documented in the docstring without a type and @@ -575,8 +575,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: .. versionadded:: 3.4 .. confval:: napoleon_custom_sections - :type: ``Optional[Sequence[str | Sequence[str, str]]]`` - :default: ``None`` + :type: :code-py:`Optional[Sequence[str | Sequence[str, str]]]` + :default: :code-py:`None` Add a list of custom sections to include, expanding the list of parsed sections.