Fix reStructuredText warnings

docs/iris/src/developers_guide/deprecations.rst

@@ -31,7 +31,7 @@ Under these circumstances the following points apply:
    :func:`iris._deprecation.warn_deprecated`, which is a
    simple wrapper to :func:`warnings.warn` with the signature
    `warn_deprecation(message, **kwargs)`.
-- Where possible, your deprecation warning should include advice on
+ - Where possible, your deprecation warning should include advice on
    how to avoid using the deprecated API. For example, you might
    reference a preferred API, or more detailed documentation elsewhere.
  - You must update the docstring for the deprecated API to include a

docs/iris/src/developers_guide/graphics_tests.rst

@@ -6,7 +6,7 @@ Graphics tests
 The only practical way of testing plotting functionality is to check actual
 output plots.
 For this, a basic 'graphics test' assertion operation is provided in the method
-:method:`iris.tests.IrisTest.check_graphic` :  This tests plotted output for a
+:meth:`iris.tests.IrisTest.check_graphic` :  This tests plotted output for a
 match against a stored reference.
 A "graphics test" is any test which employs this.
 
@@ -49,7 +49,7 @@ the Iris repository.
 This consists of :
 
  * using a perceptual 'image hash' of the outputs (see
-   <<https://github.com/JohannesBuchner/imagehash>) as the basis for checking
+   https://github.com/JohannesBuchner/imagehash) as the basis for checking
    test results.
  * storing the hashes of 'known accepted results' for each test in a
    database in the repo (which is actually stored in 
@@ -62,44 +62,46 @@ This consists of :
 
 BRIEF...
 There should be sufficient work-flow detail here to allow an iris developer to:
-    * understand the new check graphic test process
-    * understand the steps to take and tools to use to add a new graphic test
-    * understand the steps to take and tools to use to diagnose and fix an graphic test failure
+
+ * understand the new check graphic test process
+ * understand the steps to take and tools to use to add a new graphic test
+ * understand the steps to take and tools to use to diagnose and fix an graphic test failure
 
 
 Basic workflow
 ==============
-#   If you notice that a graphics test in the Iris testing suite has failed
-    following changes in Iris or any of its dependencies, this is the process
-    you now need to follow:
-
-#1. Create a directory in iris/lib/iris/tests called 'result_image_comparison'.
-#2. From your Iris root directory, run the tests by using the command:
-    ``python setup.py test``.
-#3. Navigate to iris/lib/iris/tests and run the command: ``python idiff.py``.
-    This will open a window for you to visually inspect the changes to the
-    graphic and then either accept or reject the new result.
-#4. Upon acceptance of a change or a new image, a copy of the output PNG file
-    is added to the reference image repository in
-    https://github.com/SciTools/test-images-scitools.  The file is named
-    according to the image hash value, as ``<hash>.png``.
-#5. The hash value of the new result is added into the relevant set of 'valid
-    result hashes' in the image result database file,
-    ``tests/results/imagerepo.json``.
-#6. The tests must now be re-run, and the 'new' result should be accepted.
-    Occasionally there are several graphics checks in a single test, only the
-    first of which will be run should it fail.  If this is the case, then you
-    may well encounter further graphical test failures in your next runs, and
-    you must repeat the process until all the graphical tests pass.
-#7. To add your changes to Iris, you need to make two pull requests.  The first
-    should be made to the test-images-scitools repository, and this should
-    contain all the newly-generated png files copied into the folder named
-    'image_files'.
-#8. The second pull request should be created in the Iris repository, and should
-    only include the change to the image results database
-    (``tests/results/imagerepo.json``) :
-    This pull request must contain a reference to the matching one in
-    test-images-scitools.
+
+If you notice that a graphics test in the Iris testing suite has failed
+following changes in Iris or any of its dependencies, this is the process
+you now need to follow:
+
+#. Create a directory in iris/lib/iris/tests called 'result_image_comparison'.
+#. From your Iris root directory, run the tests by using the command: 
+   ``python setup.py test``.
+#. Navigate to iris/lib/iris/tests and run the command: ``python idiff.py``.
+   This will open a window for you to visually inspect the changes to the
+   graphic and then either accept or reject the new result.
+#. Upon acceptance of a change or a new image, a copy of the output PNG file
+   is added to the reference image repository in
+   https://github.com/SciTools/test-images-scitools.  The file is named
+   according to the image hash value, as ``<hash>.png``.
+#. The hash value of the new result is added into the relevant set of 'valid
+   result hashes' in the image result database file,
+   ``tests/results/imagerepo.json``.
+#. The tests must now be re-run, and the 'new' result should be accepted.
+   Occasionally there are several graphics checks in a single test, only the
+   first of which will be run should it fail.  If this is the case, then you
+   may well encounter further graphical test failures in your next runs, and
+   you must repeat the process until all the graphical tests pass.
+#. To add your changes to Iris, you need to make two pull requests.  The first
+   should be made to the test-images-scitools repository, and this should
+   contain all the newly-generated png files copied into the folder named
+   'image_files'.
+#. The second pull request should be created in the Iris repository, and should
+   only include the change to the image results database
+   (``tests/results/imagerepo.json``) :
+   This pull request must contain a reference to the matching one in
+   test-images-scitools.
 
 Note: the Iris pull-request will not test out successfully in Travis until the
 test-images-scitools pull request has been merged :  This is because there is

docs/iris/src/developers_guide/pulls.rst

@@ -18,70 +18,86 @@ The Iris Check List
 
 * Have you provided a helpful description of the Pull Request?
   I.E. what has changed and why.  This should include:
+
  * the aim of the change ; the problem addressed ; a link to the issue.
  * how the change has been delivered.
  * a "What's New" entry, submitted as a new file added in the pull request.
    See `Contributing a "What's New" entry`_.
 
 * Do all the tests pass locally?
+
  * The Iris tests may be run with ``python setup.py test`` which has a command 
    line utility included.
 
 * Have new tests been provided for all additional functionality?
 
 * Do all modified and new sourcefiles pass PEP8?
+
  * PEP8_ is the Python source code style guide.
  * There is a python module for checking pep8 compliance: python-pep8_
  * a standard Iris test checks that all sourcefiles meet PEP8 compliance
    (see "iris.tests.test_coding_standards.TestCodeFormat").
 
 * Do all modified and new sourcefiles have a correct, up-to-date copyright
   header?
+
  * a standard Iris test checks that all sourcefiles include a copyright
    message, including the correct year of the latest change
    (see "iris.tests.test_coding_standards.TestLicenseHeaders").
 
 * Has the documentation been updated to explain all new or changed features?
+
  * refer to the developer guide on docstrings_
 
 * Have code examples been provided inside docstrings, where relevant?
+
  * these are strongly recommended as concrete (working) examples always
    considerably enhance the documentation.
+
   * live test code can be included in docstrings.
+
    * See for example :data:`iris.cube.Cube.data`
    * Details at http://www.sphinx-doc.org/en/stable/ext/doctest.html
+
   * The documentation tests may be run with ``make doctest``, from within the
     ``./docs/iris`` subdirectory.
 
 * Have you provided a 'whats new' contribution?
+
  * this should be done for all changes that affect API or behaviour.
    See :ref:`whats_new_contributions`
 
 * Does the documentation build without errors?
+
  * The documentation is built using ``make html`` in ``./docs/iris``.
 
 * Do the documentation and code-example tests pass?
+
  * Run with ``make doctest`` and ``make extest``, from within the subdirectory
    ``./docs/iris``.
  * note that code examples must *not* raise deprecations.  This is now checked
    and will result in an error.
    When an existing code example encounters a deprecation, it must be fixed.
 
 * Has the travis file been updated to reflect any dependency updates?
+
  * ``./.travis.yml`` is used to manage the continuous integration testing.
  * the files ``./conda-requirements.yml`` and
     ``./minimal-conda-requirements.yml`` are used to define the software
     environments used, using the conda_ package manager.
 
 * Have you provided updates to supporting projects for test or example data?
+
  * the following separate repos are used to manage larger files used by tests
    and code examples :
+
   * iris-test-data_ is a github project containing all the data to support the
     tests.
   * iris-sample-data_ is a github project containing all the data to support
     the gallery and examples.
   * test-images-scitools_ is a github project containing reference plot images
-    to support iris graphics tests : see :ref:`test graphics images`.
+    to support iris graphics tests : see :ref:`developer_graphics_tests`.
+
  * If new files are required by tests or code examples, they must be added to
    the appropriate supporting project via a suitable pull-request.
    This new 'supporting pull request' should be referenced in the main Iris
@@ -93,6 +109,6 @@ The Iris Check List
 .. _conda: http://conda.readthedocs.io/en/latest/
 .. _iris-test-data: https://github.com/SciTools/iris-test-data
 .. _iris-sample-data: https://github.com/SciTools/iris-sample-data
-.. _test-images-scitools https://github.com/SciTools/test-images-scitools
+.. _test-images-scitools: https://github.com/SciTools/test-images-scitools
 .. _docstrings: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/docstrings.html
 .. _Contributing a "What's New" entry: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/whats_new_contributions.html

docs/iris/src/userguide/interpolation_and_regridding.rst

@@ -17,10 +17,12 @@ upon existing interpolation schemes implemented by SciPy.
 In Iris we refer to the avaliable types of interpolation and regridding as
 `schemes`. The following are the interpolation schemes that are currently
 available in Iris:
+
  * linear interpolation (:class:`iris.analysis.Linear`), and
  * nearest-neighbour interpolation (:class:`iris.analysis.Nearest`).
 
 The following are the regridding schemes that are currently available in Iris:
+
  * linear regridding (:class:`iris.analysis.Linear`),
  * nearest-neighbour regridding (:class:`iris.analysis.Nearest`), and
  * area-weighted regridding (:class:`iris.analysis.AreaWeighted`, first-order conservative).
@@ -33,6 +35,7 @@ Interpolation
 
 Interpolating a cube is achieved with the :meth:`~iris.cube.Cube.interpolate`
 method. This method expects two arguments:
+
  #. the sample points to interpolate, and
  #. the second argument being the interpolation scheme to use.
 
@@ -41,9 +44,11 @@ The result is a new cube, interpolated at the sample points.
 Sample points must be defined as an iterable of ``(coord, value(s))`` pairs.
 The `coord` argument can be either a coordinate name or coordinate instance.
 The specified coordinate must exist on the cube being interpolated! For example:
+
  * coordinate names and scalar sample points: ``[('latitude', 51.48), ('longitude', 0)]``,
  * a coordinate instance and a scalar sample point: ``[(cube.coord('latitude'), 51.48)]``, and
  * a coordinate name and a NumPy array of sample points: ``[('longitude', np.linspace(-11, 2, 14))]``
+
 are all examples of valid sample points.
 
 The values for coordinates that correspond to date/times can be supplied as
@@ -164,6 +169,7 @@ extrapolating values makes little physical sense.
 The extrapolation mode is controlled by the ``extrapolation_mode`` keyword.
 For the available interpolation schemes available in Iris, the ``extrapolation_mode``
 keyword must be one of:
+
  * ``extrapolate`` -- the extrapolation points will be calculated by extending the gradient of the closest two points,
  * ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate,
  * ``nan`` -- the extrapolation points will be be set to NaN,
@@ -195,6 +201,7 @@ intensive part of an interpolation is setting up the interpolator.
 
 To cache an interpolator you must set up an interpolator scheme and call the
 scheme's interpolator method. The interpolator method takes as arguments:
+
  #. a cube to be interpolated, and
  #. an iterable of coordinate names or coordinate instances of the coordinates that are to be interpolated over.
 
@@ -232,6 +239,7 @@ regridding is based on the **horizontal** grid of *another cube*.
 
 Regridding a cube is achieved with the :meth:`cube.regrid() <iris.cube.Cube.regrid>` method.
 This method expects two arguments: 
+
  #. *another cube* that defines the target grid onto which the cube should be regridded, and
  #. the regridding scheme to use.
 
@@ -265,9 +273,12 @@ mode when defining the regridding scheme.
 
 For the available regridding schemes in Iris, the ``extrapolation_mode`` keyword
 must be one of:
+
  * ``extrapolate`` --
+
     * for :class:`~iris.analysis.Linear` the extrapolation points will be calculated by extending the gradient of the closest two points.
     * for :class:`~iris.analysis.Nearest` the extrapolation points will take their value from the nearest source point.
+
  * ``nan`` -- the extrapolation points will be be set to NaN.
  * ``error`` -- a ValueError exception will be raised, notifying an attempt to extrapolate.
  * ``mask`` -- the extrapolation points will always be masked, even if the source data is not a MaskedArray.
@@ -379,6 +390,7 @@ intensive part of a regrid is setting up the regridder.
 
 To cache a regridder you must set up a regridder scheme and call the
 scheme's regridder method. The regridder method takes as arguments:
+
  #. a cube (that is to be regridded) defining the source grid, and
  #. a cube defining the target grid to regrid the source cube to.
 

docs/iris/src/whatsnew/1.10.rst

@@ -148,20 +148,20 @@ Deprecations
 * The :func:`iris.fileformats.pp.as_pairs` and :func:`iris.fileformats.grib.as_pairs` are deprecated.  These are replaced with :func:`iris.fileformats.pp.save_pairs_from_cube` and :func:`iris.fileformats.grib.save_pairs_from_cube`.
 * ``iris.fileformats.pp_packing`` has been deprecated. Please install the separate `mo_pack <https://github.com/SciTools/mo_pack>`_ package instead. This provides the same functionality.
 * Deprecated logging functions (currently used only for rules logging):  
- :data:`iris.config.iris.config.RULE_LOG_DIR`,
- :data:`iris.config.iris.config.RULE_LOG_IGNORE` and
- :data:`iris.fileformats.rules.log`.
+  :data:`iris.config.iris.config.RULE_LOG_DIR`,
+  :data:`iris.config.iris.config.RULE_LOG_IGNORE` and
+  :data:`iris.fileformats.rules.log`.
 
 * Deprecated all the remaining text rules mechanisms:  
- :class:`iris.fileformats.rules.DebugString`,
- :class:`iris.fileformats.rules.CMAttribute`,
- :class:`iris.fileformats.rules.CMCustomAttribute`,
- :class:`iris.fileformats.rules.CoordAndDims`,
- :class:`iris.fileformats.rules.Rule`,
- :class:`iris.fileformats.rules.FunctionRule`,
- :class:`iris.fileformats.rules.ProcedureRule`,
- :class:`iris.fileformats.rules.RulesContainer` and
- :func:`iris.fileformats.rules.calculate_forecast_period`.
+  :class:`iris.fileformats.rules.DebugString`,
+  :class:`iris.fileformats.rules.CMAttribute`,
+  :class:`iris.fileformats.rules.CMCustomAttribute`,
+  :class:`iris.fileformats.rules.CoordAndDims`,
+  :class:`iris.fileformats.rules.Rule`,
+  :class:`iris.fileformats.rules.FunctionRule`,
+  :class:`iris.fileformats.rules.ProcedureRule`,
+  :class:`iris.fileformats.rules.RulesContainer` and
+  :func:`iris.fileformats.rules.calculate_forecast_period`.
 
 * Deprecated the custom pp save rules mechanism implemented by the functions :func:`iris.fileformats.pp.add_save_rules` and :func:`iris.fileformats.pp.reset_save_rules`. The functions :func:`iris.fileformats.pp.as_fields`, :func:`iris.fileformats.pp.as_pairs` and :func:`iris.fileformats.pp.save_fields` provide alternative means of achieving the same ends.
 

docs/iris/src/whatsnew/1.8.rst

@@ -63,10 +63,12 @@ Iris 1.8 features
 * :func:`iris.cube.CubeList.concatenate` now works with `biggus <https://biggus.readthedocs.io/>`_ arrays and so
   now supports concatenation of cubes with deferred data.
 * Improvements to NetCDF saving through using biggus:
+
  * A cube's lazy data payload will still be lazy after saving; the data will not
    be loaded into memory by the save operation.
  * Cubes with data payloads larger than system memory can now be saved to NetCDF
    through biggus streaming the data to disk.
+
 * :func:`iris.util.demote_dim_coord_to_aux_coord` and :func:`iris.util.promote_aux_coord_to_dim_coord`
   allow a coordinate to be easily demoted or promoted within a cube.
 * :func:`iris.util.squeeze` removes all length 1 dimensions from a cube, and demotes
@@ -96,10 +98,12 @@ Iris 1.8 features
   :class:`~iris.aux_factory.AuxCoordFactory` fails.
 * Supported :class:`aux coordinate factories <iris.aux_factory.AuxCoordFactory>`
   have been extended to include:
+
  * ``ocean sigma coordinate``,
  * ``ocean s coordinate``,
  * ``ocean s coordinate, generic form 1``, and
  * ``ocean s coordinate, generic form 2``.
+
 * :meth:`iris.cube.Cube.intersection` now supports taking a points-only intersection.
   Any bounds on intersected coordinates are ignored but retained.
 * The FF loader's known handled grids now includes ``Grid 21``.

docs/iris/src/whatsnew/2.0.rst

@@ -74,8 +74,9 @@ all existing toggles in :attr:`iris.FUTURE` now default to :data:`True`.
  * :attr:`iris.Future.cell_datetime_objects`
 
    * Use of this FUTURE toggle is now deprecated.
-   *  :class:`iris.coords.Cell` objects in time coordinates now contain datetime objects by default and not numbers.
-      For example::
+   * :class:`iris.coords.Cell` objects in time coordinates now contain datetime objects by default and not numbers.
+     For example::
+
         >>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
         >>> print(cube.coord('time').cell(0).point)
             1998-12-01 00:00:00
@@ -102,6 +103,7 @@ all existing toggles in :attr:`iris.FUTURE` now default to :data:`True`.
      'UNLIMITED' length.
    * You can manually specify cube dimension coordinates to save with 'UNLIMITED'
      length. For example::
+
        >>> iris.save(my_cube, 'my_result_file.nc', unlimited_dimensions=['latitude'])
 
  * :attr:`iris.Future.clip_latitudes`
@@ -238,6 +240,7 @@ been removed. In particular:
 
 * The deprecated module ``iris.analysis.interpolate`` has been removed, along
   with the following deprecated classes and functions:
+
     * ``iris.analysis.interpolate.linear``
     * ``iris.analysis.interpolate.nearest_neighbour_data_value``
     * ``iris.analysis.interpolate.regrid``

docs/iris/src/whitepapers/um_files_loading.rst

@@ -305,6 +305,7 @@ For hybrid height levels (LBVC=65):
 
 See an example printout of a hybrid height cube,
 :ref:`here <hybrid_cube_printout>`:
+
     Notice that this contains all of the above coordinates --
     'model_level_number', 'sigma', 'level_height' and the derived 'altitude'.
 
@@ -383,6 +384,7 @@ the values actually present in the source fields for each of the elements.
 
 See an example printout of a forecast data cube,
 :ref:`here <cube-statistics_forecast_printout>` :
+
     Notice that this example contains all of the above coordinates -- 'time',
     'forecast_period' and 'forecast_reference_time'.  In this case the data are
     forecasts, so 'time' is a dimension, 'forecast_period' varies with time and