fix the failing docs (pydata#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`

Author: keewis

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

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
 --------------------

pyproject.toml

@@ -27,33 +27,33 @@ 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"
 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 = [
   "setuptools>=42",
   "setuptools-scm>=7",
 ]
 
+[tool.setuptools]
+packages = ["xarray"]
+
 [tool.setuptools_scm]
 fallback_version = "9999"
 

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

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