Update documentation dependencies (#53)

Use the latest sphinx, theme, and plugins. Had to make some adjustments
for things to work with the recent versions. In particular, replacing
sphinx-panels with sphinx-design.

.github/workflows/docs.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       REQUIREMENTS: env/requirements-docs.txt env/requirements-build.txt
-      PYTHON: 3.9
+      PYTHON: "3.10"
 
     steps:
       # Cancel any previous run of the test job
@@ -62,14 +62,10 @@ 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: |
@@ -89,17 +85,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 --quiet --file requirements-full.txt python==$PYTHON
 
       - name: List installed packages
-        run: mamba list
+        run: conda list
 
       - name: Build source and wheel distributions
         run: |

.gitignore

@@ -18,3 +18,4 @@ MANIFEST
 .coverage.*
 *.ipynb
 **/_version_generated.py
+doc/sg_execution_times.rst

doc/Makefile

@@ -25,6 +25,7 @@ clean:
 	rm -rf $(BUILDDIR)/doctrees
 	rm -rf $(BUILDDIR)/linkcheck
 	rm -rf api/generated
+	rm -rf gallery
 	rm -rf .ipynb_checkpoints
 
 clean-all: clean

doc/conf.py

@@ -33,25 +33,18 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
-    "sphinx_panels",
+    "sphinx_design",
     "sphinx_gallery.gen_gallery",
     "jupyter_sphinx",
 ]
 
-# Disable including boostrap CSS for sphinx_panels since it's already included
-# with sphinx-book-theme
-panels_add_bootstrap_css = False
-panels_css_variables = {
-    "tabs-color-label-inactive": "hsla(231, 99%, 66%, 0.5)",
-}
-
 # Configuration to include links to other project docs when referencing
 # functions/classes
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/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),
     "pooch": ("https://www.fatiando.org/pooch/latest/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
 }
@@ -103,7 +96,7 @@
 # -----------------------------------------------------------------------------
 html_title = f'{project} <span class="project-version">{version}</span>'
 html_short_title = project
-html_logo = "_static/ensaio-logo.png"
+# html_logo = "_static/ensaio-logo.png"
 html_favicon = "_static/favicon.png"
 html_last_updated_fmt = "%b %d, %Y"
 html_copy_source = True

doc/gallery_src/alps-gps-velocity.py

@@ -67,7 +67,7 @@
             y=data.latitude,
             direction=[angle, length * scale_factor],
             style="v0.15c+e",
-            color="blue",
+            fill="blue",
             pen="1p,blue",
         )
         # Plot a quiver caption
@@ -76,7 +76,7 @@
             y=42,
             direction=[[0], [1 * scale_factor]],
             style="v0.15c+e",
-            color="blue",
+            fill="blue",
             pen="1p,blue",
         )
         fig.text(
@@ -96,7 +96,7 @@
         fig.plot(
             x=data.longitude,
             y=data.latitude,
-            color=data.velocity_up_mmyr,
+            fill=data.velocity_up_mmyr,
             style="c0.2c",
             cmap=True,
             pen="0.5p,black",

doc/gallery_src/britain-magnetic.py

@@ -52,7 +52,7 @@
     x=data.longitude,
     y=data.latitude,
     style="c0.02c",
-    color=data.total_field_anomaly_nt,
+    fill=data.total_field_anomaly_nt,
     cmap=True,
     projection="M15c",
 )

doc/gallery_src/british-columbia-lidar.py

@@ -51,7 +51,7 @@
 )
 pygmt.makecpt(cmap="viridis", series=[data.elevation_m.min(), data.elevation_m.max()])
 fig.plot(
-    x=data.longitude, y=data.latitude, color=data.elevation_m, cmap=True, style="c0.05c"
+    x=data.longitude, y=data.latitude, fill=data.elevation_m, cmap=True, style="c0.05c"
 )
 fig.colorbar(frame='af+l"elevation [m]"')
 fig.show()

doc/gallery_src/bushveld-gravity.py

@@ -64,7 +64,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    color=data.gravity_disturbance_mgal,
+    fill=data.gravity_disturbance_mgal,
     cmap=True,
     style="c0.1c",
 )

doc/gallery_src/caribbean-bathymetry.py

@@ -51,7 +51,7 @@
 )
 pygmt.makecpt(cmap="viridis", series=[data.depth_m.min(), data.depth_m.max()])
 fig.plot(
-    x=data.longitude, y=data.latitude, color=data.depth_m, cmap=True, style="c0.02c"
+    x=data.longitude, y=data.latitude, fill=data.depth_m, cmap=True, style="c0.02c"
 )
 fig.colorbar(frame='af+l"bathymetric depth [m]"')
 fig.coast(land="#666666")

doc/gallery_src/osborne-magnetic.py

@@ -56,7 +56,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    color=data.total_field_anomaly_nt,
+    fill=data.total_field_anomaly_nt,
     style="c0.075c",
     cmap=True,
 )

doc/gallery_src/sierra-negra-topography.py

@@ -52,7 +52,7 @@
 )
 pygmt.makecpt(cmap="viridis", series=[data.elevation_m.min(), data.elevation_m.max()])
 fig.plot(
-    x=data.longitude, y=data.latitude, color=data.elevation_m, cmap=True, style="c0.01c"
+    x=data.longitude, y=data.latitude, fill=data.elevation_m, cmap=True, style="c0.01c"
 )
 fig.colorbar(frame='af+l"elevation [m]"')
 fig.show()

doc/gallery_src/southern-africa-gravity.py

@@ -54,7 +54,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    color=data.gravity_mgal,
+    fill=data.gravity_mgal,
     cmap=True,
     style="c0.05c",
 )

doc/index.rst

@@ -2,13 +2,9 @@
 
 .. raw:: html
 
-    <h1 class="display-2 text-center">
-      Ensaio
-    </h1>
-
-.. raw:: html
-
-    <p class="centered lead front-page-callout">
+    <img class="mx-auto d-block dark-light" src="./_static/ensaio-logo.svg" width="100">
+    <h1 class="display-1 text-center">Ensaio</h1>
+    <p class="text-center lead front-page-callout">
       Practice datasets to probe your code
     </p>
     <img class="front-page-banner" src="_static/banner.png" alt="A sampling of our datasets">
@@ -24,70 +20,77 @@ caching the data on your computer.
 This means that datasets are only downloaded if they can't be found on your
 computer already.
 
-.. panels::
-    :header: text-center text-large
-    :card: border-1 m-1 text-center
+.. grid:: 1 2 1 2
+    :margin: 5 5 0 0
+    :padding: 0 0 0 0
+    :gutter: 4
 
-    **Getting started**
-    ^^^^^^^^^^^^^^^^^^^
+    .. grid-item-card:: :octicon:`info` Getting started
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    New to Ensaio? Start here!
+        New to Ensaio? Start here!
 
-    .. link-button:: using
-        :type: ref
-        :text: Downloading data
-        :classes: btn-outline-primary btn-block stretched-link
+        .. button-ref:: using
+            :ref-type: ref
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
 
-    ---
+    .. grid-item-card:: :octicon:`paintbrush` Browse our datasets
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    **Need help?**
-    ^^^^^^^^^^^^^^
+        Take a look at what's available
 
-    Ask on our community channels
+        .. button-ref:: gallery
+            :ref-type: ref
+            :color: primary
+            :outline:
+            :expand:
 
-    .. link-button:: https://www.fatiando.org/contact
-        :type: url
-        :text: Join the conversation
-        :classes: btn-outline-primary btn-block stretched-link
+    .. grid-item-card:: :octicon:`comment-discussion` Need help?
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    ---
+        Ask on our community channels.
 
-    **Browse our datasets**
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        .. button-link:: https://www.fatiando.org/contact
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
 
-    Take a look at what's available
+            Join the conversation :octicon:`link-external`
 
-    .. link-button:: gallery
-        :type: ref
-        :text: Gallery
-        :classes: btn-outline-primary btn-block stretched-link
+    .. grid-item-card:: :octicon:`file-badge` Reference documentation
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    ---
+        A list of modules and functions.
 
-    **Reference documentation**
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        .. button-ref:: api
+            :ref-type: ref
+            :color: primary
+            :outline:
+            :expand:
 
-    A list of modules and functions
-
-    .. link-button:: api
-        :type: ref
-        :text: API reference
-        :classes: btn-outline-primary btn-block stretched-link
+----
 
 .. seealso::
 
     Ensaio is a part of the
     `Fatiando a Terra <https://www.fatiando.org/>`_ project.
 
 
-----
-
-
-Table of contents
------------------
-
 .. toctree::
     :caption: User Guide
+    :hidden:
     :maxdepth: 1
 
     install.rst
@@ -97,6 +100,7 @@ Table of contents
 
 .. toctree::
     :caption: Reference
+    :hidden:
     :maxdepth: 1
 
     api/index.rst
@@ -106,6 +110,7 @@ Table of contents
 
 .. toctree::
     :caption: Community
+    :hidden:
 
     Join the community <https://www.fatiando.org/contact/>
     Code of Conduct <https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md>

env/requirements-docs.txt

@@ -1,12 +1,12 @@
-sphinx==4.3.*
-sphinx-book-theme==0.1.*
-sphinx-gallery==0.10.*
-sphinx-panels==0.6.*
-jupyter-sphinx==0.3.*
+sphinx==7.2.*
+sphinx-book-theme==1.1.*
+sphinx-gallery==0.15.*
+sphinx-design==0.5.*
+jupyter-sphinx==0.5.*
 numpy
 pandas
 xarray
 netcdf4
-pygmt==0.5.0
-gmt==6.2.0
+pygmt==0.11.0
+gmt==6.5.0
 ipython

environment.yml

@@ -3,7 +3,7 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python==3.9
+  - python==3.10
   - pip
   - make
   # Run
@@ -16,17 +16,17 @@ dependencies:
   - pytest-cov
   - coverage
   # Documentation
-  - sphinx==4.3.*
-  - sphinx-book-theme==0.1.*
-  - sphinx-gallery==0.10.*
-  - sphinx-panels==0.6.*
-  - jupyter-sphinx==0.3.*
+  - sphinx==7.2.*
+  - sphinx-book-theme==1.1.*
+  - sphinx-gallery==0.15.*
+  - sphinx-design==0.5.*
+  - jupyter-sphinx==0.5.*
   - numpy
   - pandas
   - xarray
   - netcdf4
-  - pygmt==0.5.0
-  - gmt==6.2.0
+  - pygmt==0.11.0
+  - gmt==6.5.0
   - ipython
   # Style
   - black