Use granular syntax highlighting for the Napoleon extension

Author: AA-Turner

doc/usage/extensions/napoleon.rst

@@ -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