Comment rendering (#4689)

* used numpy docstrings to fix docs rendering

* comment rejig

* apply numpydoc strings

* corrected notes

* updated docstring guidance.

* added explicit mention of numpydoc strings

* added whatsnew

* added whatsnew PR ref

* Update lib/iris/fileformats/nimrod_load_rules.py

Co-authored-by: Will Benfold <[email protected]>

* Update docs/src/whatsnew/latest.rst

Co-authored-by: Will Benfold <[email protected]>

* review actions.

Co-authored-by: Will Benfold <[email protected]>

Author: tkknight

docs/src/developers_guide/contributing_pull_request_checklist.rst

@@ -34,7 +34,8 @@ is merged.  Before submitting a pull request please consider this list.
    should be generated too, see :ref:`cirrus_test_env`.
 
 #. **Check the source documentation been updated to explain all new or changed
-   features**.  See :ref:`docstrings`.
+   features**.  Note, we now use numpydoc strings.  Any touched code should
+   be updated to use the docstrings formatting. See :ref:`docstrings`.
 
 #. **Include code examples inside the docstrings where appropriate**.  See
    :ref:`contributing.documentation.testing`.

docs/src/developers_guide/documenting/docstrings.rst

@@ -8,10 +8,10 @@ Every public object in the Iris package should have an appropriate docstring.
 This is important as the docstrings are used by developers to understand
 the code and may be read directly in the source or via the :ref:`Iris`.
 
-This document has been influenced by the following PEP's,
-
-* Attribute Docstrings :pep:`224`
-* Docstring Conventions :pep:`257`
+.. note::
+   As of April 2022 we are looking to adopt `numpydoc`_ strings as standard.
+   We aim to complete the adoption over time as we do changes to the codebase.
+   For examples of use see `numpydoc`_ and `sphinxcontrib-napoleon`_
 
 For consistency always use:
 
@@ -20,91 +20,14 @@ For consistency always use:
   docstrings.
 * ``u"""Unicode triple-quoted string"""`` for Unicode docstrings
 
-All docstrings should be written in reST (reStructuredText) markup.  See the
-:ref:`reST_quick_start` for more detail.
-
-There are two forms of docstrings: **single-line** and **multi-line**
-docstrings.
-
-
-Single-Line Docstrings
-======================
-
-The single line docstring of an object must state the **purpose** of that
-object, known as the **purpose section**. This terse overview must be on one
-line and ideally no longer than 80 characters.
-
-
-Multi-Line Docstrings
-=====================
-
-Multi-line docstrings must consist of at least a purpose section akin to the
-single-line docstring, followed by a blank line and then any other content, as
-described below. The entire docstring should be indented to the same level as
-the quotes at the docstring's first line.
-
-
-Description
------------
-
-The multi-line docstring  *description section* should expand on what was
-stated in the one line *purpose section*. The description section should try
-not to document *argument* and *keyword argument* details. Such information
-should be documented in the following *arguments and keywords section*.
-
-
-Sample Multi-Line Docstring
----------------------------
-
-Here is a simple example of a standard docstring:
-
-.. literalinclude:: docstrings_sample_routine.py
-
-This would be rendered as:
-
-   .. currentmodule:: documenting.docstrings_sample_routine
-
-   .. automodule:: documenting.docstrings_sample_routine
-      :members:
-      :undoc-members:
-
-Additionally, a summary can be extracted automatically, which would result in:
-
-   .. autosummary::
-
-      documenting.docstrings_sample_routine.sample_routine
-
-
-Documenting Classes
-===================
-
-The class constructor should be documented in the docstring for its
-``__init__`` or ``__new__`` method. Methods should be documented by their own
-docstring, not in the class header itself.
-
-If a class subclasses another class and its behaviour is mostly inherited from
-that class, its docstring should mention this and summarise the differences.
-Use the verb "override" to indicate that a subclass method replaces a
-superclass method and does not call the superclass method; use the verb
-"extend" to indicate that a subclass method calls the superclass method
-(in addition to its own behaviour).
-
-
-Attribute and Property Docstrings
----------------------------------
-
-Here is a simple example of a class containing an attribute docstring and a
-property docstring:
-
-.. literalinclude:: docstrings_attribute.py
+All docstrings can use reST (reStructuredText) markup to augment the
+rendered formatting.  See the :ref:`reST_quick_start` for more detail.
 
-This would be rendered as:
+For more information including examples pleasee see:
 
-   .. currentmodule:: documenting.docstrings_attribute
+* `numpydoc`_
+* `sphinxcontrib-napoleon`_
 
-   .. automodule:: documenting.docstrings_attribute
-      :members:
-      :undoc-members:
 
-.. note:: The purpose section of the property docstring **must** state whether
-          the property is read-only.
+.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html#style-guide
+.. _sphinxcontrib-napoleon: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

docs/src/whatsnew/latest.rst

@@ -114,6 +114,10 @@ This document explains the changes made to Iris for this release
 #. `@tkknight`_ adopted the `PyData Sphinx Theme`_ for the documentation.
    (:discussion:`4344`, :pull:`4661`)
 
+#. `@tkknight`_ updated our developers guidance to show our intent to adopt
+   numpydoc strings and fixed some API documentation rendering.
+   See :ref:`docstrings`. (:issue:`4657`, :pull:`4689`)
+
 
 💼 Internal
 ===========

lib/iris/fileformats/dot.py

@@ -59,14 +59,18 @@ def _dot_path():
 
 
 def save(cube, target):
-    """Save a dot representation of the cube.
-
-    Args:
+    """
+    Save a dot representation of the cube.
 
-        * cube   - A :class:`iris.cube.Cube`.
-        * target - A filename or open file handle.
+    Args
+    ----
+    cube: :class:`iris.cube.Cube`.
+    target
+        A filename or open file handle.
 
-    See also :func:`iris.io.save`.
+    See Also
+    --------
+    :func:`iris.io.save`.
 
     """
     if isinstance(target, str):
@@ -87,19 +91,23 @@ def save(cube, target):
 
 def save_png(source, target, launch=False):
     """
-    Produces a "dot" instance diagram by calling dot and optionally launching the resulting image.
-
-    Args:
+    Produce a "dot" instance diagram by calling dot and optionally launching
+    the resulting image.
 
-        * source - A :class:`iris.cube.Cube`, or dot filename.
-        * target - A filename or open file handle.
-                   If passing a file handle, take care to open it for binary output.
+    Args
+    ----
+    source: :class:`iris.cube.Cube`, or dot filename.
+    target
+        A filename or open file handle.
+        If passing a file handle, take care to open it for binary output.
 
-    Kwargs:
+    **kwargs
+        * launch
+            Display the image. Default is False.
 
-        * launch - Display the image. Default is False.
-
-    See also :func:`iris.io.save`.
+    See Also
+    --------
+    :func:`iris.io.save`.
 
     """
     # From cube or dot file?
@@ -152,11 +160,13 @@ def save_png(source, target, launch=False):
 
 
 def cube_text(cube):
-    """Return a DOT text representation a `iris.cube.Cube`.
-
-    Args:
+    """
+    Return a DOT text representation a `iris.cube.Cube`.
 
-     * cube  -  The cube for which to create DOT text.
+    Args
+    ----
+    cube
+       The cube for which to create DOT text.
 
     """
     # We use r'' type string constructor as when we type \n in a string without the r'' constructor
@@ -283,13 +293,14 @@ def cube_text(cube):
 
 def _coord_text(label, coord):
     """
-    Returns a string containing the dot representation for a single coordinate node.
-
-    Args:
+    Return a string containing the dot representation for a single coordinate
+    node.
 
-    * label
+    Args
+    ----
+    label
         The dot ID of the coordinate node.
-    * coord
+    coord
         The coordinate to convert.
 
     """
@@ -315,14 +326,16 @@ def _coord_text(label, coord):
 
 def _coord_system_text(cs, uid):
     """
-    Returns a string containing the dot representation for a single coordinate system node.
+    Return a string containing the dot representation for a single coordinate
+    system node.
 
-    Args:
-
-    * cs
+    Args
+    ----
+    cs
         The coordinate system to convert.
-    * uid
-        The uid allows/distinguishes non-identical CoordSystems of the same type.
+    uid
+        The uid allows/distinguishes non-identical CoordSystems of the same
+        type.
 
     """
     attrs = []
@@ -341,15 +354,15 @@ def _coord_system_text(cs, uid):
 
 def _dot_node(indent, id, name, attributes):
     """
-    Returns a string containing the dot representation for a single node.
-
-    Args:
+    Return a string containing the dot representation for a single node.
 
-     * id
+    Args
+    ----
+    id
         The ID of the node.
-     * name
+    name
         The visual name of the node.
-     * attributes
+    attributes
         An iterable of (name, value) attribute pairs.
 
     """