upgrade sphinx (pydata#6415)

* pin sphinx to v4 * update the docs environment * use the new official name of the RTD configuration file * reorder the RTD sections * [skip-ci] * temporarily pin jinja2 [skip-ci] * drop the pin altogether, but disallow sphinx=4.4.0 [skip-ci] `extlinks` in `sphinx=4.4.0` creates warnings for hard-coded links — which are useful, but it's impossible to ignore false positives. * attempt to follow most of the advice of the extlinks checker * [skip-ci] * fix some broken links to PRs * [skip-ci]
benbovy · Mar 26, 2022 · 8f42bfd · 8f42bfd
1 parent 81715fd
commit 8f42bfd
Show file tree

Hide file tree

Showing 6 changed files with 18 additions and 18 deletions.
diff --git a/readthedocs.yml → .readthedocs.yaml b/readthedocs.yml → .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: []
diff --git 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
@@ -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
@@ -33,7 +34,7 @@ dependencies:
   - sphinx-book-theme >= 0.0.38
   - sphinx-copybutton
   - sphinx-panels
-  - sphinx<4
+  - sphinx!=4.4.0
   - zarr>=2.4
   - pip:
       - sphinxext-rediraffe

diff --git a/doc/developers-meeting.rst b/doc/developers-meeting.rst
@@ -7,7 +7,7 @@ The meeting occurs on `Zoom <https://us02web.zoom.us/j/88251613296?pwd=azZsSkU1U
 
 Notes for the meeting are kept `here <https://hackmd.io/@U4W-olO3TX-hc-cvbjNe4A/xarray-dev-meeting/edit>`__.
 
-There is a `GitHub issue <https://github.com/pydata/xarray/issues/4001>`__ 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
@@ -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
@@ -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 <https://github.com/pydata/xarray/issues/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 <https://github.com/pydata/xarray/issues/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 <https://github.com/pydata/xarray/issues/4118>`__.).
+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 <https://github.com/JaneliaSciComp/xarray-multiscale>`__.),

diff --git 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 <https://github.com/dcherian>`_.
 - Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims`
-  (pull:`3331`, pull:`3331`). By `Justus Magin <https://github.com/keewis>`_.
+  (:pull:`3331`, :pull:`3331`). By `Justus Magin <https://github.com/keewis>`_.
 - 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`).
@@ -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 <https://github.com/pydata/xarray/issues/1829>`__
+  - :issue:`Xarray Github issue discussing dropping Python 2 <1829>`
   - `Python 3 Statement <http://www.python3statement.org/>`__
   - `Tips on porting to Python 3 <https://docs.python.org/3/howto/pyporting.html>`__