From b313d9f06df826c9677915ecc716c3605ddae2b3 Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 3 Nov 2021 13:23:00 +0100 Subject: [PATCH 01/11] pin sphinx to v4 --- ci/requirements/doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index f722b9d1535..440a9cb3f0d 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -32,7 +32,7 @@ dependencies: - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - sphinx-panels - - sphinx<4 + - sphinx<5 - zarr>=2.4 - pip: - sphinxext-rediraffe From 0ccd9af5574a1fe8aa336d3edd9eef64b444495f Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 13:09:19 +0100 Subject: [PATCH 02/11] update the docs environment --- ci/requirements/doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 0b26a0adbaa..fd82bd0252d 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -4,7 +4,7 @@ channels: - conda-forge - nodefaults dependencies: - - python=3.8 + - python=3.9 - bottleneck - cartopy - cfgrib>=0.9 From 80f24b96cd33917b8336c095e7ae2895f3a5ab90 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 13:13:41 +0100 Subject: [PATCH 03/11] use the new official name of the RTD configuration file --- readthedocs.yml => .readthedocs.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename readthedocs.yml => .readthedocs.yaml (100%) diff --git a/readthedocs.yml b/.readthedocs.yaml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yaml From d7c144a19b97658f422e9565ace8a4563ac88571 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 13:15:26 +0100 Subject: [PATCH 04/11] reorder the RTD sections --- .readthedocs.yaml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 89266a10fc8..cf263cc666a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,10 +1,14 @@ version: 2 + build: os: ubuntu-20.04 tools: python: mambaforge-4.10 -sphinx: - fail_on_warning: true + conda: environment: ci/requirements/doc.yml + +sphinx: + fail_on_warning: true + formats: [] From 2affd1fcafcae704643d39ad7252e2d05d14135c Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 13:15:45 +0100 Subject: [PATCH 05/11] [skip-ci] From 0e46b9ecd0d428997173bbf0773f936bcc98efd5 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 13:30:57 +0100 Subject: [PATCH 06/11] temporarily pin jinja2 [skip-ci] --- ci/requirements/doc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index fd82bd0252d..9283a3d27f1 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -13,6 +13,7 @@ dependencies: - ipykernel - ipython - iris>=2.3 + - jinja2<3.1 # remove once nbconvert fixed the use of removed functions - jupyter_client - matplotlib-base - nbsphinx From e038862f7b8d13902a0c78e03a8c9eb56d4ead7d Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 14:11:03 +0100 Subject: [PATCH 07/11] drop the pin altogether, but disallow sphinx=4.4.0 [skip-ci] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `extlinks` in `sphinx=4.4.0` creates warnings for hard-coded links — which are useful, but it's impossible to ignore false positives. --- ci/requirements/doc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 9283a3d27f1..3d4e149619e 100644 --- a/ci/requirements/doc.yml +++ b/ci/requirements/doc.yml @@ -34,7 +34,7 @@ dependencies: - sphinx-book-theme >= 0.0.38 - sphinx-copybutton - sphinx-panels - - sphinx<5 + - sphinx!=4.4.0 - zarr>=2.4 - pip: - sphinxext-rediraffe From 2ca0f6b0225f137ac8f45c9b63f7d4c0c4029bf4 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 14:41:23 +0100 Subject: [PATCH 08/11] attempt to follow most of the advice of the extlinks checker --- doc/developers-meeting.rst | 2 +- doc/internals/extending-xarray.rst | 4 +--- doc/roadmap.rst | 13 +++++-------- doc/whats-new.rst | 2 +- 4 files changed, 8 insertions(+), 13 deletions(-) diff --git a/doc/developers-meeting.rst b/doc/developers-meeting.rst index 7034d3c722e..ff706b17af8 100644 --- a/doc/developers-meeting.rst +++ b/doc/developers-meeting.rst @@ -7,7 +7,7 @@ The meeting occurs on `Zoom `__. -There is a `GitHub issue `__ for changes to the meeting. +There is a :issue:`GitHub issue <4001>` for changes to the meeting. You can subscribe to this calendar to be notified of changes: diff --git a/doc/internals/extending-xarray.rst b/doc/internals/extending-xarray.rst index c9591e7d3cd..2951ce10f21 100644 --- a/doc/internals/extending-xarray.rst +++ b/doc/internals/extending-xarray.rst @@ -18,12 +18,10 @@ easy to inadvertently use internal APIs when subclassing, which means that your code may break when xarray upgrades. Furthermore, many builtin methods will only return native xarray objects. -The standard advice is to use `composition over inheritance`__, but +The standard advice is to use :issue:`composition over inheritance <706>`, but reimplementing an API as large as xarray's on your own objects can be an onerous task, even if most methods are only forwarding to xarray implementations. -__ https://github.com/pydata/xarray/issues/706 - If you simply want the ability to call a function with the syntax of a method call, then the builtin :py:meth:`~xarray.DataArray.pipe` method (copied from pandas) may suffice. diff --git a/doc/roadmap.rst b/doc/roadmap.rst index d4098cfd35a..eeaaf10813b 100644 --- a/doc/roadmap.rst +++ b/doc/roadmap.rst @@ -114,8 +114,7 @@ xarray's data model, e.g., as attributes on the ``Dataset`` and coordinates in xarray operations, but will no longer would need to have a one-to-one correspondence with coordinate variables. Instead, an index should be able to refer to multiple (possibly multidimensional) -coordinates that define it. See `GH -1603 `__ for full details +coordinates that define it. See :issue:`1603` for full details. Specific tasks: @@ -182,11 +181,9 @@ backends means that users can not easily build backend interface for xarray in third-party libraries. The idea of refactoring the backends API and exposing it to users was -originally proposed in `GH -1970 `__. The idea would -be to develop a well tested and generic backend base class and -associated utilities for external use. Specific tasks for this -development would include: +originally proposed in :issue:`1970`. The idea would be to develop a +well tested and generic backend base class and associated utilities +for external use. Specific tasks for this development would include: - Exposing an abstract backend for writing new storage systems. - Exposing utilities for features like automatic closing of files, @@ -225,7 +222,7 @@ examples include: A new tree-like data structure which is essentially a structured hierarchical collection of Datasets could represent these cases, and would instead map to -multiple netCDF groups (see `GH4118 `__.). +multiple netCDF groups (see :issue:`4118`). Currently there are several libraries which have wrapped xarray in order to build domain-specific data structures (e.g. `xarray-multiscale `__.), diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 405a96806be..32872b38c27 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -2732,7 +2732,7 @@ Removes inadvertently introduced setup dependency on pytest-runner will be Python 3 only, but older versions of xarray will always be available for Python 2.7 users. For the more details, see: - - `Xarray Github issue discussing dropping Python 2 `__ + - :issue:`Xarray Github issue discussing dropping Python 2 <1829>` - `Python 3 Statement `__ - `Tips on porting to Python 3 `__ From f92a2fe34212239c5672d180f6ae947f00035201 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 14:51:24 +0100 Subject: [PATCH 09/11] [skip-ci] From 04d47373c7ed48ce4673aa6205471b48885fb4b6 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 15:22:11 +0100 Subject: [PATCH 10/11] fix some broken links to PRs --- doc/whats-new.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 32872b38c27..37cf3af85b9 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -2148,7 +2148,7 @@ Documentation - Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). By `Deepak Cherian `_. - Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` - (pull:`3331`, pull:`3331`). By `Justus Magin `_. + (:pull:`3331`, :pull:`3331`). By `Justus Magin `_. - Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, :py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`, :py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna` (:pull:`3328`). From e72d8f15b266f0ed58f740b0faf8d9d4e495f78d Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 26 Mar 2022 15:23:38 +0100 Subject: [PATCH 11/11] [skip-ci]