From e00e31b9ea7fcd562f75f6c657d02c4f81867095 Mon Sep 17 00:00:00 2001
From: Justus Magin <keewis@users.noreply.github.com>
Date: Fri, 15 Sep 2023 15:26:24 +0200
Subject: [PATCH] fix the failing docs (#8188)

* don't try to build with `pandas=2.1.0`

one of the docstrings we inherit from `pandas` is malformatted in that version

* reorder the project metadata sections

* source the exhaustive list of optional deps from `pyproject.toml`

* link to the new location of the colormap tutorial in matplotlib

* also convert the narrative documentation to `pyproject.toml`
---
 ci/requirements/doc.yml                  |  2 +-
 doc/getting-started-guide/installing.rst | 12 +++++------
 pyproject.toml                           | 26 ++++++++++++------------
 xarray/plot/dataarray_plot.py            |  4 ++--
 xarray/plot/dataset_plot.py              |  2 +-
 5 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml
index fe1fe91bb51..bc35d0db894 100644
--- a/ci/requirements/doc.yml
+++ b/ci/requirements/doc.yml
@@ -21,7 +21,7 @@ dependencies:
   - numba
   - numpy>=1.21
   - packaging>=21.3
-  - pandas>=1.4
+  - pandas>=1.4,!=2.1.0
   - pooch
   - pip
   - pre-commit
diff --git a/doc/getting-started-guide/installing.rst b/doc/getting-started-guide/installing.rst
index ff8650bc0ff..e8c498b6664 100644
--- a/doc/getting-started-guide/installing.rst
+++ b/doc/getting-started-guide/installing.rst
@@ -135,13 +135,13 @@ We also maintain other dependency sets for different subsets of functionality::
 The above commands should install most of the `optional dependencies`_. However,
 some packages which are either not listed on PyPI or require extra
 installation steps are excluded. To know which dependencies would be
-installed, take a look at the ``[options.extras_require]`` section in
-``setup.cfg``:
+installed, take a look at the ``[project.optional-dependencies]`` section in
+``pyproject.toml``:
 
-.. literalinclude:: ../../setup.cfg
-   :language: ini
-   :start-at: [options.extras_require]
-   :end-before: [options.package_data]
+.. literalinclude:: ../../pyproject.toml
+   :language: toml
+   :start-at: [project.optional-dependencies]
+   :end-before: [build-system]
 
 Development versions
 --------------------
diff --git a/pyproject.toml b/pyproject.toml
index 96d5361552f..c820c933def 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,19 +27,6 @@ dependencies = [
   "pandas>=1.4",
 ]
 
-[project.optional-dependencies]
-accel = ["scipy", "bottleneck", "numbagg", "flox"]
-complete = ["xarray[accel,io,parallel,viz]"]
-io = ["netCDF4", "h5netcdf", "scipy", 'pydap; python_version<"3.10"', "zarr", "fsspec", "cftime", "pooch"]
-parallel = ["dask[complete]"]
-viz = ["matplotlib", "seaborn", "nc-time-axis"]
-
-[tool.setuptools]
-packages = ["xarray"]
-
-[project.entry-points."xarray.chunkmanagers"]
-dask = "xarray.core.daskmanager:DaskManager"
-
 [project.urls]
 Documentation = "https://docs.xarray.dev"
 SciPy2015-talk = "https://www.youtube.com/watch?v=X0pAhJgySxk"
@@ -47,6 +34,16 @@ homepage = "https://xarray.dev/"
 issue-tracker = "https://github.com/pydata/xarray/issues"
 source-code = "https://github.com/pydata/xarray"
 
+[project.entry-points."xarray.chunkmanagers"]
+dask = "xarray.core.daskmanager:DaskManager"
+
+[project.optional-dependencies]
+accel = ["scipy", "bottleneck", "numbagg", "flox"]
+complete = ["xarray[accel,io,parallel,viz]"]
+io = ["netCDF4", "h5netcdf", "scipy", 'pydap; python_version<"3.10"', "zarr", "fsspec", "cftime", "pooch"]
+parallel = ["dask[complete]"]
+viz = ["matplotlib", "seaborn", "nc-time-axis"]
+
 [build-system]
 build-backend = "setuptools.build_meta"
 requires = [
@@ -54,6 +51,9 @@ requires = [
   "setuptools-scm>=7",
 ]
 
+[tool.setuptools]
+packages = ["xarray"]
+
 [tool.setuptools_scm]
 fallback_version = "9999"
 
diff --git a/xarray/plot/dataarray_plot.py b/xarray/plot/dataarray_plot.py
index 4df1938f89f..1e9324791da 100644
--- a/xarray/plot/dataarray_plot.py
+++ b/xarray/plot/dataarray_plot.py
@@ -789,7 +789,7 @@ def _plot1d(plotfunc):
         be either ``'viridis'`` (if the function infers a sequential
         dataset) or ``'RdBu_r'`` (if the function infers a diverging
         dataset).
-        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:tutorials/colors/colormaps>`
+        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:users/explain/colors/colormaps>`
         for more information.
 
         If *seaborn* is installed, ``cmap`` may also be a
@@ -1325,7 +1325,7 @@ def _plot2d(plotfunc):
         The mapping from data values to color space. If not provided, this
         will be either be ``'viridis'`` (if the function infers a sequential
         dataset) or ``'RdBu_r'`` (if the function infers a diverging dataset).
-        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:tutorials/colors/colormaps>`
+        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:users/explain/colors/colormaps>`
         for more information.
 
         If *seaborn* is installed, ``cmap`` may also be a
diff --git a/xarray/plot/dataset_plot.py b/xarray/plot/dataset_plot.py
index 4f703045f17..edb32b73d98 100644
--- a/xarray/plot/dataset_plot.py
+++ b/xarray/plot/dataset_plot.py
@@ -103,7 +103,7 @@ def _dsplot(plotfunc):
         be either ``'viridis'`` (if the function infers a sequential
         dataset) or ``'RdBu_r'`` (if the function infers a diverging
         dataset).
-        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:tutorials/colors/colormaps>`
+        See :doc:`Choosing Colormaps in Matplotlib <matplotlib:users/explain/colors/colormaps>`
         for more information.
 
         If *seaborn* is installed, ``cmap`` may also be a