diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py index 0af6d8fcce..e84742bb9c 100644 --- a/docs/iris/src/conf.py +++ b/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" diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py index 161819a3ac..c30f4e96fd 100644 --- a/lib/iris/analysis/maths.py +++ b/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: diff --git a/lib/iris/io/__init__.py b/lib/iris/io/__init__.py index 31cd862d85..5ea2d07350 100644 --- a/lib/iris/io/__init__.py +++ b/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. diff --git a/requirements/ci/py36.yml b/requirements/ci/py36.yml index 74fdfd4b66..cd02a2524c 100644 --- a/requirements/ci/py36.yml +++ b/requirements/ci/py36.yml @@ -46,3 +46,6 @@ dependencies: - sphinx-copybutton - sphinx-gallery - sphinx_rtd_theme + - pip + - pip: + - sphinxcontrib-napoleon diff --git a/requirements/ci/py37.yml b/requirements/ci/py37.yml index a8168db52c..fbd3b1a1f6 100644 --- a/requirements/ci/py37.yml +++ b/requirements/ci/py37.yml @@ -46,3 +46,6 @@ dependencies: - sphinx-copybutton - sphinx-gallery - sphinx_rtd_theme + - pip + - pip: + - sphinxcontrib-napoleon diff --git a/requirements/docs.txt b/requirements/docs.txt index 78585630e5..16658de90c 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -4,3 +4,4 @@ sphinx sphinx-copybutton sphinx-gallery sphinx_rtd_theme +sphinxcontrib-napoleon