diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py index 0af6d8fcce..13b836b073 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" @@ -244,6 +261,8 @@ def autolog(message): "http://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf", "http://code.google.com/p/msysgit/downloads/list", "http://schacon.github.com/git", + "https://github.com/SciTools/iris/pull", + "https://github.com/SciTools/iris/issue", ] # list of sources to exclude from the build. diff --git a/docs/iris/src/developers_guide/contributing_documentation.rst b/docs/iris/src/developers_guide/contributing_documentation.rst index 4185c74c78..7c18ddda64 100644 --- a/docs/iris/src/developers_guide/contributing_documentation.rst +++ b/docs/iris/src/developers_guide/contributing_documentation.rst @@ -11,9 +11,6 @@ improve the documentation for all users. Any change to the Iris project whether it is a bugfix, new feature or documentation update must use the :ref:`development-workflow`. -.. contents:: Contents: - :local: - Requirements ~~~~~~~~~~~~ diff --git a/docs/iris/src/whatsnew/1.0.rst b/docs/iris/src/whatsnew/1.0.rst index 79afd8cf1a..11d29320b6 100644 --- a/docs/iris/src/whatsnew/1.0.rst +++ b/docs/iris/src/whatsnew/1.0.rst @@ -4,12 +4,6 @@ v1.0 (17 Oct 2012) This document explains the changes made to Iris for this release (:doc:`View all changes `.) - -.. contents:: Skip to section: - :local: - :depth: 3 - - With the release of Iris 1.0, we have broadly completed the transition to the CF data model, and established a stable foundation for future work. Following this release we plan to deliver significant performance diff --git a/docs/iris/src/whatsnew/1.1.rst b/docs/iris/src/whatsnew/1.1.rst index ea85dbc42c..f2b0995fa0 100644 --- a/docs/iris/src/whatsnew/1.1.rst +++ b/docs/iris/src/whatsnew/1.1.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.10.rst b/docs/iris/src/whatsnew/1.10.rst index b5dfc1974b..3f51287fa1 100644 --- a/docs/iris/src/whatsnew/1.10.rst +++ b/docs/iris/src/whatsnew/1.10.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.11.rst b/docs/iris/src/whatsnew/1.11.rst index d04355b800..e0d46d0f09 100644 --- a/docs/iris/src/whatsnew/1.11.rst +++ b/docs/iris/src/whatsnew/1.11.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.12.rst b/docs/iris/src/whatsnew/1.12.rst index 1d7fc8f978..2bb7090dd2 100644 --- a/docs/iris/src/whatsnew/1.12.rst +++ b/docs/iris/src/whatsnew/1.12.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.13.rst b/docs/iris/src/whatsnew/1.13.rst index 30b3731d96..2d3b3ffce5 100644 --- a/docs/iris/src/whatsnew/1.13.rst +++ b/docs/iris/src/whatsnew/1.13.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.2.rst b/docs/iris/src/whatsnew/1.2.rst index 982a68add6..d4bb863a3b 100644 --- a/docs/iris/src/whatsnew/1.2.rst +++ b/docs/iris/src/whatsnew/1.2.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.3.rst b/docs/iris/src/whatsnew/1.3.rst index fd6f2cfef9..9a2ac2eba1 100644 --- a/docs/iris/src/whatsnew/1.3.rst +++ b/docs/iris/src/whatsnew/1.3.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.4.rst b/docs/iris/src/whatsnew/1.4.rst index 7f96643f5f..29f2079af8 100644 --- a/docs/iris/src/whatsnew/1.4.rst +++ b/docs/iris/src/whatsnew/1.4.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.5.rst b/docs/iris/src/whatsnew/1.5.rst index 07f54e15cf..ea7965fe15 100644 --- a/docs/iris/src/whatsnew/1.5.rst +++ b/docs/iris/src/whatsnew/1.5.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.6.rst b/docs/iris/src/whatsnew/1.6.rst index 068311db5f..3855d71479 100644 --- a/docs/iris/src/whatsnew/1.6.rst +++ b/docs/iris/src/whatsnew/1.6.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.7.rst b/docs/iris/src/whatsnew/1.7.rst index e60c1083d9..f6e818fedf 100644 --- a/docs/iris/src/whatsnew/1.7.rst +++ b/docs/iris/src/whatsnew/1.7.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.8.rst b/docs/iris/src/whatsnew/1.8.rst index 17432d7267..579d4d20c5 100644 --- a/docs/iris/src/whatsnew/1.8.rst +++ b/docs/iris/src/whatsnew/1.8.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/1.9.rst b/docs/iris/src/whatsnew/1.9.rst index 77d03b5de3..c9d91bf33c 100644 --- a/docs/iris/src/whatsnew/1.9.rst +++ b/docs/iris/src/whatsnew/1.9.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/2.0.rst b/docs/iris/src/whatsnew/2.0.rst index 577e8fea22..fbd012dd1f 100644 --- a/docs/iris/src/whatsnew/2.0.rst +++ b/docs/iris/src/whatsnew/2.0.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/2.1.rst b/docs/iris/src/whatsnew/2.1.rst index 311e8c251b..ef03f023b2 100644 --- a/docs/iris/src/whatsnew/2.1.rst +++ b/docs/iris/src/whatsnew/2.1.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/2.2.rst b/docs/iris/src/whatsnew/2.2.rst index 314f84355f..48280895fe 100644 --- a/docs/iris/src/whatsnew/2.2.rst +++ b/docs/iris/src/whatsnew/2.2.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/2.3.rst b/docs/iris/src/whatsnew/2.3.rst index ec6bb3254b..5997a7f4dc 100644 --- a/docs/iris/src/whatsnew/2.3.rst +++ b/docs/iris/src/whatsnew/2.3.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/2.4.rst b/docs/iris/src/whatsnew/2.4.rst index ca7be20cd8..c62e84c129 100644 --- a/docs/iris/src/whatsnew/2.4.rst +++ b/docs/iris/src/whatsnew/2.4.rst @@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release (:doc:`View all changes `.) -.. contents:: Skip to section: - :local: - :depth: 3 - - Features ======== diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index 7a72d43a15..be4062b788 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -1,3 +1,5 @@ +.. include:: ../common_links.inc + ************ @@ -231,9 +233,20 @@ This document explains the changes made to Iris for this release user guide to clarify how ``Units`` are handled during cube arithmetic. (:pull:`3803`) +* `@tkknight`_ overhauled the :ref:`developers_guide` including information on + getting involved in becoming a contributor and general structure of the + guide. This resolves :issue:`2170`, :issue:`2331`, :issue:`3453`, + :issue:`314`, :issue:`2902`. (:pull:`3852`) + * `@rcomer`_ added argument descriptions to the :class:`~iris.coords.DimCoord` docstring. (:pull:`3681`) +* `@tkknight`_ added two url's to be ignored for the ``make linkcheck``. This + will ensure the Iris github project is not repeatedly hit during the + linkcheck for issues and pull requests as it can result in connection + refused and thus travis-ci_ job failures. For more information on linkcheck, + see :ref:`contributing.documentation.testing`. (:pull:`3873`) + 💼 Internal =========== 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