Use napolean extension in docs to handle numpy docstrings too

docs/iris/src/conf.py

@@ -114,6 +114,7 @@ def autolog(message):
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
+    "sphinx.ext.napoleon",
     # TODO: Spelling extension disabled until the dependencies can be included
     # "sphinxcontrib.spelling",
     "sphinx_gallery.gen_gallery",
@@ -125,6 +126,22 @@ def autolog(message):
     "generate_package_rst",
 ]
 
+# -- Napoleon extension -------------------------------------------------------
+# See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True  # includes dunders in api doc
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_use_keyword = True
+napoleon_custom_sections = None
+
 # -- spellingextension --------------------------------------------------------
 # See https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html
 spelling_lang = "en_GB"

lib/iris/analysis/maths.py

@@ -1098,7 +1098,7 @@ def __call__(
             Dimension along which to apply `other` if it's a coordinate that is
             not found in `cube`
 
-        * **kwargs_data_func:
+        * kwargs_data_func:
             Keyword arguments that get passed on to the data_func.
 
         Returns:

lib/iris/io/__init__.py

@@ -287,8 +287,8 @@ def add_saver(file_extension, new_saver):
 
     Args:
 
-        * file_extension - A string such as "pp" or "my_format".
-        * new_saver      - A function of the form ``my_saver(cube, target)``.
+    * file_extension: A string such as "pp" or "my_format".
+    * new_saver:      A function of the form ``my_saver(cube, target)``.
 
     See also :func:`iris.io.save`
 
@@ -351,24 +351,27 @@ def save(source, target, saver=None, **kwargs):
 
     Args:
 
-        * source    - A :class:`iris.cube.Cube`, :class:`iris.cube.CubeList` or
-                      sequence of cubes.
-        * target    - A filename (or writeable, depending on file format).
-                      When given a filename or file, Iris can determine the
-                      file format.
+    * source:
+        :class:`iris.cube.Cube`, :class:`iris.cube.CubeList` or
+        sequence of cubes.
+    * target:
+        A filename (or writeable, depending on file format).
+        When given a filename or file, Iris can determine the
+        file format.
 
     Kwargs:
 
-        * saver     - Optional. Specifies the file format to save.
-                      If omitted, Iris will attempt to determine the format.
-
-                      If a string, this is the recognised filename extension
-                      (where the actual filename may not have it).
-                      Otherwise the value is a saver function, of the form:
-                      ``my_saver(cube, target)`` plus any custom keywords. It
-                      is assumed that a saver will accept an ``append`` keyword
-                      if it's file format can handle multiple cubes. See also
-                      :func:`iris.io.add_saver`.
+    * saver:
+        Optional. Specifies the file format to save.
+        If omitted, Iris will attempt to determine the format.
+
+        If a string, this is the recognised filename extension
+        (where the actual filename may not have it).
+        Otherwise the value is a saver function, of the form:
+        ``my_saver(cube, target)`` plus any custom keywords. It
+        is assumed that a saver will accept an ``append`` keyword
+        if it's file format can handle multiple cubes. See also
+        :func:`iris.io.add_saver`.
 
     All other keywords are passed through to the saver function; see the
     relevant saver documentation for more information on keyword arguments.

requirements/ci/py36.yml

@@ -46,3 +46,6 @@ dependencies:
   - sphinx-copybutton
   - sphinx-gallery
   - sphinx_rtd_theme
+  - pip
+  - pip:
+    - sphinxcontrib-napoleon

requirements/ci/py37.yml

@@ -46,3 +46,6 @@ dependencies:
   - sphinx-copybutton
   - sphinx-gallery
   - sphinx_rtd_theme
+  - pip
+  - pip:
+    - sphinxcontrib-napoleon

requirements/docs.txt

@@ -4,3 +4,4 @@ sphinx
 sphinx-copybutton
 sphinx-gallery
 sphinx_rtd_theme
+sphinxcontrib-napoleon