From 481c1b6d62d1f6e7df5b04a3bbb457387e3ad89b Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 14 Jun 2020 12:50:32 +0200 Subject: [PATCH 1/6] add blackdoc to the pre-commit configuration --- .pre-commit-config.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 26bf4803ef6..8fc56faf1cf 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: master + hooks: + - id: blackdoc - repo: https://gitlab.com/pycqa/flake8 rev: 3.7.9 hooks: From 80f580a5b45931bad6a44311a6d48258279f13fe Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 14 Jun 2020 15:46:42 +0200 Subject: [PATCH 2/6] use the stable version of blackdoc --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8fc56faf1cf..a4c53aad845 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,7 +12,7 @@ repos: hooks: - id: black - repo: https://github.com/keewis/blackdoc - rev: master + rev: stable hooks: - id: blackdoc - repo: https://gitlab.com/pycqa/flake8 From de3b9a41d747ba04c30bbda66c57bed7824b3076 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 14 Jun 2020 17:47:06 +0200 Subject: [PATCH 3/6] run blackdoc on all files --- doc/dask.rst | 5 +++- doc/internals.rst | 9 ++++--- doc/plotting.rst | 4 +-- xarray/core/computation.py | 52 +++++++++++++++++++++++++------------- xarray/core/parallel.py | 5 +++- 5 files changed, 49 insertions(+), 26 deletions(-) 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/xarray/core/computation.py b/xarray/core/computation.py index cecd4fd8e70..fd21ce8ccd5 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 , From 0541f6f7026cb7c7de9f4196d33ae4759cdb825a Mon Sep 17 00:00:00 2001 From: Keewis Date: Thu, 25 Jun 2020 13:59:21 +0200 Subject: [PATCH 4/6] add blackdoc to the linter / formatting tools section --- doc/contributing.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/contributing.rst b/doc/contributing.rst index 51dba2bb0cc..797de63fae0 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -347,7 +347,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 +359,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 . From 7651594acfbcd405f2906d5a8f1e5b42b7f2a36b Mon Sep 17 00:00:00 2001 From: Keewis Date: Thu, 25 Jun 2020 14:00:56 +0200 Subject: [PATCH 5/6] use language names to enable syntax highlighting --- doc/contributing.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/contributing.rst b/doc/contributing.rst index 797de63fae0..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 From 301c0580ad557e0c8f55b8363339def3e4d93a07 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 26 Jun 2020 15:20:57 +0200 Subject: [PATCH 6/6] update whats-new.rst --- doc/whats-new.rst | 3 +++ 1 file changed, 3 insertions(+) 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 `_.