Blackdoc (#4177)

* add blackdoc to the pre-commit configuration

* use the stable version of blackdoc

* run blackdoc on all files

* add blackdoc to the linter / formatting tools section

* use language names to enable syntax highlighting

* update whats-new.rst

Author: keewis

.pre-commit-config.yaml

@@ -11,6 +11,10 @@ repos:
     rev: stable
     hooks:
       - id: black
+  - repo: https://github.com/keewis/blackdoc
+    rev: stable
+    hooks:
+      - id: blackdoc
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.7.9
     hooks:

doc/contributing.rst

@@ -148,7 +148,7 @@ We'll now kick off a two-step process:
 1. Install the build dependencies
 2. Build and install xarray
 
-.. code-block:: none
+.. code-block:: sh
 
    # Create and activate the build environment
    # This is for Linux and MacOS. On Windows, use py37-windows.yml instead.
@@ -162,7 +162,10 @@ We'll now kick off a two-step process:
    # Build and install xarray
    pip install -e .
 
-At this point you should be able to import *xarray* from your locally built version::
+At this point you should be able to import *xarray* from your locally
+built version:
+
+.. code-block:: sh
 
    $ python  # start an interpreter
    >>> import xarray
@@ -256,7 +259,9 @@ Some other important things to know about the docs:
 - The tutorials make heavy use of the `ipython directive
   <http://matplotlib.org/sampledoc/ipython_directive.html>`_ sphinx extension.
   This directive lets you put code in the documentation which will be run
-  during the doc build. For example::
+  during the doc build. For example:
+
+  .. code:: rst
 
       .. ipython:: python
 
@@ -290,7 +295,7 @@ Requirements
 Make sure to follow the instructions on :ref:`creating a development environment above <contributing.dev_env>`, but
 to build the docs you need to use the environment file ``ci/requirements/doc.yml``.
 
-.. code-block:: none
+.. code-block:: sh
 
     # Create and activate the docs environment
     conda env create -f ci/requirements/doc.yml
@@ -347,7 +352,10 @@ Code Formatting
 
 xarray uses several tools to ensure a consistent code format throughout the project:
 
-- `Black <https://black.readthedocs.io/en/stable/>`_ for standardized code formatting
+- `Black <https://black.readthedocs.io/en/stable/>`_ for standardized
+  code formatting
+- `blackdoc <https://blackdoc.readthedocs.io/en/stable/>`_ for
+  standardized code formatting in documentation
 - `Flake8 <http://flake8.pycqa.org/en/latest/>`_ for general code quality
 - `isort <https://github.com/timothycrosley/isort>`_ for standardized order in imports.
   See also `flake8-isort <https://github.com/gforcada/flake8-isort>`_.
@@ -356,12 +364,13 @@ xarray uses several tools to ensure a consistent code format throughout the proj
 
 ``pip``::
 
-   pip install black flake8 isort mypy
+   pip install black flake8 isort mypy blackdoc
 
 and then run from the root of the Xarray repository::
 
    isort -rc .
    black -t py36 .
+   blackdoc -t py36 .
    flake8
    mypy .
 

doc/dask.rst

@@ -432,6 +432,7 @@ received by the applied function.
         print(da.sizes)
         return da.time
 
+
     mapped = xr.map_blocks(func, ds.temperature)
     mapped
 
@@ -461,9 +462,10 @@ Here is a common example where automated inference will not work.
     :okexcept:
 
     def func(da):
-	print(da.sizes)
+        print(da.sizes)
         return da.isel(time=[1])
 
+
     mapped = xr.map_blocks(func, ds.temperature)
 
 ``func`` cannot be run on 0-shaped inputs because it is not possible to extract element 1 along a
@@ -501,6 +503,7 @@ Notice that the 0-shaped sizes were not printed to screen. Since ``template`` ha
     def func(obj, a, b=0):
         return obj + a + b
 
+
     mapped = ds.map_blocks(func, args=[10], kwargs={"b": 10})
     expected = ds + 10 + 10
     mapped.identical(expected)

doc/internals.rst

@@ -182,9 +182,10 @@ re-open it directly with Zarr:
 
 .. ipython:: python
 
-    ds = xr.tutorial.load_dataset('rasm')
-    ds.to_zarr('rasm.zarr', mode='w')
+    ds = xr.tutorial.load_dataset("rasm")
+    ds.to_zarr("rasm.zarr", mode="w")
     import zarr
-    zgroup = zarr.open('rasm.zarr')
+
+    zgroup = zarr.open("rasm.zarr")
     print(zgroup.tree())
-    dict(zgroup['Tair'].attrs)
+    dict(zgroup["Tair"].attrs)

doc/plotting.rst

@@ -220,7 +220,7 @@ from the time and assign it as a non-dimension coordinate:
 
 .. ipython:: python
 
-    decimal_day = (air1d.time - air1d.time[0]) /  pd.Timedelta('1d')
+    decimal_day = (air1d.time - air1d.time[0]) / pd.Timedelta("1d")
     air1d_multi = air1d.assign_coords(decimal_day=("time", decimal_day))
     air1d_multi
 
@@ -911,4 +911,4 @@ One can also make line plots with multidimensional coordinates. In this case, ``
     f, ax = plt.subplots(2, 1)
     da.plot.line(x="lon", hue="y", ax=ax[0])
     @savefig plotting_example_2d_hue_xy.png
-    da.plot.line(x="lon", hue="x", ax=ax[1])
+    da.plot.line(x="lon", hue="x", ax=ax[1])

doc/whats-new.rst

@@ -197,6 +197,9 @@ Internal Changes
 - Run the ``isort`` pre-commit hook only on python source files
   and update the ``flake8`` version. (:issue:`3750`, :pull:`3711`)
   By `Justus Magin <https://github.com/keewis>`_.
+- Add `blackdoc <https://blackdoc.readthedocs.io>`_ to the list of
+  checkers for development. (:pull:`4177`)
+  By `Justus Magin <https://github.com/keewis>`_.
 - Add a CI job that runs the tests with every optional dependency
   except ``dask``. (:issue:`3794`, :pull:`3919`)
   By `Justus Magin <https://github.com/keewis>`_.

xarray/core/computation.py

@@ -1096,10 +1096,14 @@ def cov(da_a, da_b, dim=None, ddof=1):
 
     Examples
     --------
-    >>> da_a = DataArray(np.array([[1, 2, 3], [0.1, 0.2, 0.3], [3.2, 0.6, 1.8]]),
-    ...                  dims=("space", "time"),
-    ...                  coords=[('space', ['IA', 'IL', 'IN']),
-    ...                          ('time', pd.date_range("2000-01-01", freq="1D", periods=3))])
+    >>> da_a = DataArray(
+    ...     np.array([[1, 2, 3], [0.1, 0.2, 0.3], [3.2, 0.6, 1.8]]),
+    ...     dims=("space", "time"),
+    ...     coords=[
+    ...         ("space", ["IA", "IL", "IN"]),
+    ...         ("time", pd.date_range("2000-01-01", freq="1D", periods=3)),
+    ...     ],
+    ... )
     >>> da_a
     <xarray.DataArray (space: 3, time: 3)>
     array([[1. , 2. , 3. ],
@@ -1108,10 +1112,14 @@ def cov(da_a, da_b, dim=None, ddof=1):
     Coordinates:
       * space    (space) <U2 'IA' 'IL' 'IN'
       * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03
-    >>> da_b = DataArray(np.array([[0.2, 0.4, 0.6], [15, 10, 5], [3.2, 0.6, 1.8]]),
-    ...                  dims=("space", "time"),
-    ...                  coords=[('space', ['IA', 'IL', 'IN']),
-    ...                          ('time', pd.date_range("2000-01-01", freq="1D", periods=3))])
+    >>> da_b = DataArray(
+    ...     np.array([[0.2, 0.4, 0.6], [15, 10, 5], [3.2, 0.6, 1.8]]),
+    ...     dims=("space", "time"),
+    ...     coords=[
+    ...         ("space", ["IA", "IL", "IN"]),
+    ...         ("time", pd.date_range("2000-01-01", freq="1D", periods=3)),
+    ...     ],
+    ... )
     >>> da_b
     <xarray.DataArray (space: 3, time: 3)>
     array([[ 0.2,  0.4,  0.6],
@@ -1123,7 +1131,7 @@ def cov(da_a, da_b, dim=None, ddof=1):
     >>> xr.cov(da_a, da_b)
     <xarray.DataArray ()>
     array(-3.53055556)
-    >>> xr.cov(da_a, da_b, dim='time')
+    >>> xr.cov(da_a, da_b, dim="time")
     <xarray.DataArray (space: 3)>
     array([ 0.2, -0.5,  1.69333333])
     Coordinates:
@@ -1165,10 +1173,14 @@ def corr(da_a, da_b, dim=None):
 
     Examples
     --------
-    >>> da_a = DataArray(np.array([[1, 2, 3], [0.1, 0.2, 0.3], [3.2, 0.6, 1.8]]),
-    ...                  dims=("space", "time"),
-    ...                  coords=[('space', ['IA', 'IL', 'IN']),
-    ...                          ('time', pd.date_range("2000-01-01", freq="1D", periods=3))])
+    >>> da_a = DataArray(
+    ...     np.array([[1, 2, 3], [0.1, 0.2, 0.3], [3.2, 0.6, 1.8]]),
+    ...     dims=("space", "time"),
+    ...     coords=[
+    ...         ("space", ["IA", "IL", "IN"]),
+    ...         ("time", pd.date_range("2000-01-01", freq="1D", periods=3)),
+    ...     ],
+    ... )
     >>> da_a
     <xarray.DataArray (space: 3, time: 3)>
     array([[1. , 2. , 3. ],
@@ -1177,10 +1189,14 @@ def corr(da_a, da_b, dim=None):
     Coordinates:
       * space    (space) <U2 'IA' 'IL' 'IN'
       * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03
-    >>> da_b = DataArray(np.array([[0.2, 0.4, 0.6], [15, 10, 5], [3.2, 0.6, 1.8]]),
-    ...                  dims=("space", "time"),
-    ...                  coords=[('space', ['IA', 'IL', 'IN']),
-    ...                          ('time', pd.date_range("2000-01-01", freq="1D", periods=3))])
+    >>> da_b = DataArray(
+    ...     np.array([[0.2, 0.4, 0.6], [15, 10, 5], [3.2, 0.6, 1.8]]),
+    ...     dims=("space", "time"),
+    ...     coords=[
+    ...         ("space", ["IA", "IL", "IN"]),
+    ...         ("time", pd.date_range("2000-01-01", freq="1D", periods=3)),
+    ...     ],
+    ... )
     >>> da_b
     <xarray.DataArray (space: 3, time: 3)>
     array([[ 0.2,  0.4,  0.6],
@@ -1192,7 +1208,7 @@ def corr(da_a, da_b, dim=None):
     >>> xr.corr(da_a, da_b)
     <xarray.DataArray ()>
     array(-0.57087777)
-    >>> xr.corr(da_a, da_b, dim='time')
+    >>> xr.corr(da_a, da_b, dim="time")
     <xarray.DataArray (space: 3)>
     array([ 1., -1.,  1.])
     Coordinates:

xarray/core/parallel.py

@@ -252,7 +252,10 @@ def map_blocks(
     to the function being applied in ``xr.map_blocks()``:
 
     >>> xr.map_blocks(
-    ...     calculate_anomaly, array, kwargs={"groupby_type": "time.year"}, template=array,
+    ...     calculate_anomaly,
+    ...     array,
+    ...     kwargs={"groupby_type": "time.year"},
+    ...     template=array,
     ... )
     <xarray.DataArray (time: 24)>
     array([ 0.15361741, -0.25671244, -0.31600032,  0.008463  ,  0.1766172 ,