update the docs environment (pydata#7442)

* use python 3.10 in the docs environment

* require a more recent `sphinx` version

* [skip-ci]

* remove the unused pydata-sphinx-theme [skip-ci]

* pin `sphinx-book-theme` to a more recent version [skip-ci]

* try working around the theme bug [skip-ci]

* use string interpolation markers for the extlink text

* try specifying the project of a intersphinx link

* remove the empty `extra_navbar` and `navbar_footer_text` theme options

* [skip-ci]

---------

Co-authored-by: Joe Hamman <[email protected]>
Co-authored-by: Deepak Cherian <[email protected]>
Co-authored-by: Illviljan <[email protected]>

Author: 4 people

ci/requirements/doc.yml

@@ -4,7 +4,7 @@ channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - python=3.9
+  - python=3.10
   - bottleneck
   - cartopy
   - cfgrib>=0.9
@@ -23,18 +23,17 @@ dependencies:
   - pandas>=1.4
   - pooch
   - pip
-  - pydata-sphinx-theme>=0.4.3
   - pyproj
   - rasterio>=1.1
   - scipy!=1.10.0
   - seaborn
   - setuptools
   - sparse
   - sphinx-autosummary-accessors
-  - sphinx-book-theme >= 0.0.38
+  - sphinx-book-theme >= 0.3.0
   - sphinx-copybutton
   - sphinx-design
-  - sphinx!=4.4.0
+  - sphinx>=5.0
   - zarr>=2.10
   - pip:
       - sphinxext-rediraffe

doc/conf.py

@@ -97,8 +97,8 @@
 
 
 extlinks = {
-    "issue": ("https://github.com/pydata/xarray/issues/%s", "GH"),
-    "pull": ("https://github.com/pydata/xarray/pull/%s", "PR"),
+    "issue": ("https://github.com/pydata/xarray/issues/%s", "GH%s"),
+    "pull": ("https://github.com/pydata/xarray/pull/%s", "PR%s"),
 }
 
 # sphinx-copybutton configurations
@@ -244,12 +244,11 @@
     use_repository_button=True,
     use_issues_button=True,
     home_page_in_toc=False,
-    extra_navbar="",
-    navbar_footer_text="",
     extra_footer="""<p>Xarray is a fiscally sponsored project of <a href="https://numfocus.org">NumFOCUS</a>,
     a nonprofit dedicated to supporting the open-source scientific computing community.<br>
     Theme by the <a href="https://ebp.jupyterbook.org">Executable Book Project</a></p>""",
     twitter_url="https://twitter.com/xarray_devs",
+    icon_links=[],  # workaround for pydata/pydata-sphinx-theme#1220
 )
 
 

doc/user-guide/interpolation.rst

@@ -50,7 +50,7 @@ array-like, which gives the interpolated result as an array.
     # interpolation
     da.interp(time=[2.5, 3.5])
 
-To interpolate data with a :py:doc:`numpy.datetime64 <reference/arrays.datetime>` coordinate you can pass a string.
+To interpolate data with a :py:doc:`numpy.datetime64 <numpy:reference/arrays.datetime>` coordinate you can pass a string.
 
 .. ipython:: python