diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1d384e58a3c..447f0007fc2 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/doc/contributing.rst b/doc/contributing.rst index 51dba2bb0cc..9e6a3c250e9 100644 --- a/doc/contributing.rst +++ b/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 `_ 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 `, 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 `_ for standardized code formatting +- `Black `_ for standardized + code formatting +- `blackdoc `_ for + standardized code formatting in documentation - `Flake8 `_ for general code quality - `isort `_ for standardized order in imports. See also `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 . diff --git a/doc/dask.rst b/doc/dask.rst index df223982ba4..de25ee2200e 100644 --- a/doc/dask.rst +++ b/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) diff --git a/doc/internals.rst b/doc/internals.rst index 27c7c4e1d87..46c117e312b 100644 --- a/doc/internals.rst +++ b/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) \ No newline at end of file diff --git a/doc/plotting.rst b/doc/plotting.rst index f98f47f2567..72248e31b1e 100644 --- a/doc/plotting.rst +++ b/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]) \ No newline at end of file diff --git a/doc/whats-new.rst b/doc/whats-new.rst index d82be79270e..27d369dd6f7 100644 --- a/doc/whats-new.rst +++ b/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 `_. +- Add `blackdoc `_ to the list of + checkers for development. (:pull:`4177`) + By `Justus Magin `_. - Add a CI job that runs the tests with every optional dependency except ``dask``. (:issue:`3794`, :pull:`3919`) By `Justus Magin `_. diff --git a/xarray/core/computation.py b/xarray/core/computation.py index 4f4fd475c82..d8a0c53e817 100644 --- a/xarray/core/computation.py +++ b/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 array([[1. , 2. , 3. ], @@ -1108,10 +1112,14 @@ def cov(da_a, da_b, dim=None, ddof=1): Coordinates: * space (space) >> 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 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) array(-3.53055556) - >>> xr.cov(da_a, da_b, dim='time') + >>> xr.cov(da_a, da_b, dim="time") 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 array([[1. , 2. , 3. ], @@ -1177,10 +1189,14 @@ def corr(da_a, da_b, dim=None): Coordinates: * space (space) >> 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 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) array(-0.57087777) - >>> xr.corr(da_a, da_b, dim='time') + >>> xr.corr(da_a, da_b, dim="time") array([ 1., -1., 1.]) Coordinates: diff --git a/xarray/core/parallel.py b/xarray/core/parallel.py index 3a77753d0d1..86044e72dd2 100644 --- a/xarray/core/parallel.py +++ b/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, ... ) array([ 0.15361741, -0.25671244, -0.31600032, 0.008463 , 0.1766172 ,