Merge branch 'master' into docs_warning_to_error

* master: Use napolean extension in docs to handle numpy docstrings too (SciTools#3871) Added whats new for pr3873 (SciTools#3874) linkcheck ignore for iris pull and issue url (SciTools#3873) Remove all local table of contents (SciTools#3872) Added whats new entry for pr3852 (SciTools#3854)
tkknight · Sep 22, 2020 · fab8069 · fab8069
2 parents 0d27059 + 10b3f9a
commit fab8069
Show file tree

Hide file tree

Showing 27 changed files with 60 additions and 117 deletions.
diff --git 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
@@ -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
@@ -4,12 +4,6 @@ v1.0 (17 Oct 2012)
 This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
-
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. 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
@@ -5,11 +5,6 @@ This document explains the changes made to Iris for this release
 (:doc:`View all changes <index>`.)
 
 
-.. contents:: Skip to section:
-   :local:
-   :depth: 3
-
-
 Features
 ========
 

diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst
@@ -1,3 +1,5 @@
+.. include:: ../common_links.inc
+
 <unreleased>
 ************
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -4,3 +4,4 @@ sphinx
 sphinx-copybutton
 sphinx-gallery
 sphinx_rtd_theme
+sphinxcontrib-napoleon