Update the versions of documentation tools (#419)

Use the newest sphinx, themes, plugins. Had to make some adjustments to
the front page in order to adapt to the new versions. Had to stop
caching the conda packages for this to work. Something about that didn't
allow finding the latest packages.

.github/workflows/docs.yml

@@ -33,14 +33,14 @@ jobs:
     runs-on: ubuntu-latest
     env:
       REQUIREMENTS: env/requirements-build.txt env/requirements-docs.txt
-      PYTHON: 3.9
+      PYTHON: "3.10"
 
     steps:
       # Cancel any previous run of the test job
       # We pin the commit hash corresponding to v0.5.0, and not pinning the tag
       # because we are giving full access through the github.token.
       - name: Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@148d9a848c6acaf90a3ec30bc5062f646f8a4163
+        uses: styfle/cancel-workflow-action@0.9.1
         with:
           access_token: ${{ github.token }}
 
@@ -62,20 +62,15 @@ jobs:
         run: git fetch origin 'refs/tags/*:refs/tags/*'
 
       - name: Setup Miniconda
-        uses: conda-incubator/setup-miniconda@v2
+        uses: conda-incubator/setup-miniconda@v3
         with:
           python-version: ${{ env.PYTHON }}
-          miniforge-variant: Mambaforge
-          use-mamba: true
           channels: conda-forge,defaults
-          # Needed for caching
-          use-only-tar-bz2: true
-
 
       - name: Collect requirements
         run: |
           echo "Install Dependente to capture dependencies:"
-          mamba install dependente==0.1.0 -c conda-forge
+          conda install dependente==0.1.0 -c conda-forge
           echo ""
           echo "Capturing run-time dependencies:"
           dependente --source install,extras > requirements-full.txt
@@ -89,17 +84,11 @@ jobs:
           echo "Collected dependencies:"
           cat requirements-full.txt
 
-      - name: Setup caching for conda packages
-        uses: actions/cache@v3
-        with:
-          path: ~/conda_pkgs_dir
-          key: conda-${{ runner.os }}-${{ env.PYTHON }}-${{ hashFiles('requirements-full.txt') }}
-
       - name: Install requirements
-        run: mamba install --quiet --file requirements-full.txt python=$PYTHON
+        run: conda install --file requirements-full.txt python=$PYTHON -c conda-forge
 
       - name: List installed packages
-        run: mamba list
+        run: conda list
 
       - name: Build source and wheel distributions
         run: |

.gitignore

@@ -21,3 +21,4 @@ dask-worker-space
 .coverage.*
 *.ipynb
 **/_version_generated.py
+sg_execution_times.rst

doc/conf.py

@@ -42,14 +42,14 @@
 # functions/classes
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "sklearn": ("https://scikit-learn.org/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
-    "xarray": ("https://xarray.pydata.org/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
     "pooch": ("https://www.fatiando.org/pooch/latest/", None),
-    "matplotlib": ("https://matplotlib.org/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
     "dask": ("https://docs.dask.org/en/latest/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
 }
@@ -102,7 +102,9 @@
 # HTML output configuration
 # -----------------------------------------------------------------------------
 html_title = f'{project} <span class="project-version">{version}</span>'
-html_logo = "_static/verde-logo.png"
+# Don't use the logo since it gets in the way of the project name and is
+# repeated in the front page.
+# html_logo = "_static/verde-logo.png"
 html_favicon = "_static/favicon.png"
 html_last_updated_fmt = "%b %d, %Y"
 html_copy_source = True

doc/index.rst

@@ -5,6 +5,13 @@
     :margin: 5 5 0 0
     :padding: 0 0 0 0
 
+    .. grid-item::
+        :columns: 12 4 12 4
+
+        .. image:: ./_static/verde-logo.svg
+            :width: 200px
+            :class: sd-m-auto dark-light
+
     .. grid-item::
         :columns: 12 8 12 8
 
@@ -16,19 +23,12 @@
 
                 .. raw:: html
 
-                    <h1 class="display-1"><img src="_static/verde-title.svg" alt="Verde"></h1>
+                    <h1 class="display-1"><img class="dark-light" src="_static/verde-title.svg" alt="Verde"></h1>
 
         .. div:: sd-fs-3
 
             Processing and gridding spatial data, machine-learning style
 
-    .. grid-item::
-        :columns: 12 4 12 4
-
-        .. image:: ./_static/verde-logo.svg
-            :width: 200px
-            :class: sd-m-auto
-
 **Verde** is a Python library for processing spatial data (bathymetry,
 geophysics surveys, etc) and interpolating it on regular grids (i.e.,
 *gridding*).

env/requirements-docs.txt

@@ -1,11 +1,11 @@
-sphinx==4.5.*
-sphinx-book-theme==0.3.*
-sphinx-gallery==0.10.*
+sphinx==7.2.*
+sphinx-book-theme==1.1.*
+sphinx-gallery==0.15.*
 sphinx-copybutton==0.5.*
-sphinx-design==0.1.*
-matplotlib==3.5.*
+sphinx-design==0.5.*
+matplotlib==3.8.*
 cartopy>=0.20
 pyproj
-pygmt==0.6.*
-gmt==6.3.*
+pygmt==0.11.*
+gmt==6.5.*
 ipython

environment.yml

@@ -20,21 +20,21 @@ dependencies:
     - pykdtree
     - numba
     # Test
-    - matplotlib==3.5.*
+    - matplotlib==3.8.*
     - cartopy>=0.20
     - pytest
     - pytest-cov
     - pytest-mpl
     - coverage
     # Documentation
-    - sphinx==4.5.*
-    - sphinx-book-theme==0.3.*
-    - sphinx-gallery==0.10.*
+    - sphinx==7.2.*
+    - sphinx-book-theme==1.1.*
+    - sphinx-gallery==0.15.*
     - sphinx-copybutton==0.5.*
-    - sphinx-design==0.1.*
+    - sphinx-design==0.5.*
     - pyproj
-    - pygmt==0.6.*
-    - gmt==6.3.*
+    - pygmt==0.11.*
+    - gmt==6.5.*
     - ipython
     # Style
     - black