pre-commit blacked docs

.pre-commit-config.yaml

@@ -35,3 +35,8 @@ repos:
     -   id: isort
         name: isort
         args: ["--filter-files"]
+-   repo: https://github.com/asottile/blacken-docs
+    rev: v1.8.0
+    hooks:
+    -   id: blacken-docs
+        additional_dependencies: [black==21.6b0]

docs/src/developers_guide/contributing_testing.rst

@@ -69,12 +69,14 @@ Within that file the tests might look something like:
         def test_some_general_stuff(self):
             ...
 
+
     # Tests for the Cube.xml() method, focussing on the behaviour of
     # the checksums.
     class Test_xml__checksum(tests.IrisTest):
         def test_checksum_ignores_masked_values(self):
             ...
 
+
     # Tests for the Cube.add_dim_coord() method.
     class Test_add_dim_coord(tests.IrisTest):
         def test_normal_usage(self):
@@ -120,6 +122,7 @@ Within that file the tests might look something like:
         def test_int16_big_endian(self):
             ...
 
+
     # Tests focussing on the handling of different projections.
     class TestProjection(tests.IrisTest):
         def test_no_ellipsoid(self):

docs/src/userguide/saving_iris_cubes.rst

@@ -30,9 +30,9 @@ and the keyword argument `saver` is not required.
 
     .. code-block:: python
 
-        cube = iris.load_cube('somefile.nc')
+        cube = iris.load_cube("somefile.nc")
         # The next line causes data loss in 'somefile.nc' and the cube.
-        iris.save(cube, 'somefile.nc')
+        iris.save(cube, "somefile.nc")
 
     In general, overwriting a file which is the source for any lazily loaded
     data can result in corruption. Users should proceed with caution when

docs/src/whatsnew/1.6.rst

@@ -19,11 +19,11 @@ Features
     reference coordinate will return *datetime-like* objects when invoked
     with :meth:`iris.coords.Coord.cell` or :meth:`iris.coords.Coord.cells`.
 
-    .. code-block:: python
+    .. code-block:: pycon
 
         >>> from iris.coords import DimCoord
         >>> iris.FUTURE.cell_datetime_objects = True
-        >>> coord = DimCoord([1, 2, 3], 'time', units='hours since epoch')
+        >>> coord = DimCoord([1, 2, 3], "time", units="hours since epoch")
         >>> print([str(cell) for cell in coord.cells()])
         ['1970-01-01 01:00:00', '1970-01-01 02:00:00', '1970-01-01 03:00:00']
 
@@ -44,7 +44,7 @@ Features
     which allows multiple sections of code to execute with different run-time
     behaviour.
 
-    .. code-block:: python
+    .. code-block:: pycon
 
         >>> print(iris.FUTURE)
         Future(cell_datetime_objects=False)
@@ -159,7 +159,7 @@ consuming processing, or to reap the benefit of fast-loading a pickled cube.
 
     # Determine whether to load from the cache or source.
     if iris.util.file_is_newer(cache_file, source_file):
-        with open(cache_file, 'rb') as fh:
+        with open(cache_file, "rb") as fh:
             cube = cPickle.load(fh)
     else:
         cube = iris.load_cube(source_file)
@@ -184,7 +184,8 @@ For example, an RMS weighted cube collapse is performed as follows:
 .. code-block:: python
 
     from iris.analysis import RMS
-    collapsed_cube = cube.collapsed('height', RMS, weights=weights)
+
+    collapsed_cube = cube.collapsed("height", RMS, weights=weights)
 
 
 .. _equalise:
@@ -241,7 +242,8 @@ For example, to calculate the peak time:
 .. code-block:: python
 
     from iris.analysis import PEAK
-    collapsed_cube = cube.collapsed('time', PEAK)
+
+    collapsed_cube = cube.collapsed("time", PEAK)
 
 
 Bugs Fixed

docs/src/whatsnew/latest.rst

@@ -184,6 +184,9 @@ This document explains the changes made to Iris for this release
 #. `@bjlittle`_ renamed ``iris/master`` branch to ``iris/main`` and migrated
    references of ``master`` to ``main`` within codebase. (:pull:`4202`)
 
+#. `@bjlittle`_ added the `blacken-docs`_ ``pre-commit`` hook to automate
+   ``black`` linting of documentation code blocks. (:pull:`4205`)
+
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,
     core dev names are automatically included by the common_links.inc:
@@ -198,6 +201,7 @@ This document explains the changes made to Iris for this release
     Whatsnew resources in alphabetical order:
 
 .. _abstract base class: https://docs.python.org/3/library/abc.html
+.. _blacken-docs: https://github.com/asottile/blacken-docs
 .. _deprecated numpy 1.20 aliases for builtin types: https://numpy.org/doc/1.20/release/1.20.0-notes.html#using-the-aliases-of-builtin-types-like-np-int-is-deprecated
 .. _GitHub: https://github.com/SciTools/iris/issues/new/choose
 .. _Met Office: https://www.metoffice.gov.uk/

lib/iris/io/__init__.py

@@ -402,9 +402,9 @@ def save(source, target, saver=None, **kwargs):
 
        .. code-block:: python
 
-          cube = iris.load_cube('somefile.nc')
+          cube = iris.load_cube("somefile.nc")
           # The next line causes data loss in 'somefile.nc' and the cube.
-          iris.save(cube, 'somefile.nc')
+          iris.save(cube, "somefile.nc")
 
        In general, overwriting a file which is the source for any lazily loaded
        data can result in corruption. Users should proceed with caution when