From eca3473a5b08fdf1a554a11161739453f8a942dd Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 22 Jun 2021 09:30:14 +0100 Subject: [PATCH 1/2] pre-commit blacked docs --- .pre-commit-config.yaml | 5 +++++ docs/src/developers_guide/contributing_testing.rst | 3 +++ docs/src/userguide/saving_iris_cubes.rst | 4 ++-- docs/src/whatsnew/1.6.rst | 14 ++++++++------ lib/iris/io/__init__.py | 4 ++-- 5 files changed, 20 insertions(+), 10 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f932a539d3..f255f1b66e 100644 --- a/.pre-commit-config.yaml +++ b/.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] diff --git a/docs/src/developers_guide/contributing_testing.rst b/docs/src/developers_guide/contributing_testing.rst index 486af706d3..d0c96834a9 100644 --- a/docs/src/developers_guide/contributing_testing.rst +++ b/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): diff --git a/docs/src/userguide/saving_iris_cubes.rst b/docs/src/userguide/saving_iris_cubes.rst index 237ceb18b6..c801a1fbea 100644 --- a/docs/src/userguide/saving_iris_cubes.rst +++ b/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 diff --git a/docs/src/whatsnew/1.6.rst b/docs/src/whatsnew/1.6.rst index 8b0205b86f..f1c50a3f08 100644 --- a/docs/src/whatsnew/1.6.rst +++ b/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 diff --git a/lib/iris/io/__init__.py b/lib/iris/io/__init__.py index c40e41cca8..64501afd1e 100644 --- a/lib/iris/io/__init__.py +++ b/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 From dfda62de13ff5aa1fccfd121a9fdde88b4b5c63e Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 22 Jun 2021 10:45:28 +0100 Subject: [PATCH 2/2] add whatsnew entry --- docs/src/whatsnew/latest.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 88d7008e5a..d0f6542e61 100644 --- a/docs/src/whatsnew/latest.rst +++ b/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/