Download User Guides as scripts and notebooks (#405)

Add download links to every User Guide page so they can be downloaded as Python scripts or Jupyter notebooks. Bump version of jupyter-sphinx to v0.4 so we can make use of the download roles.
fatiando · Apr 28, 2023 · 256cc2d · 256cc2d
1 parent f6d6a1e
commit 256cc2d
Show file tree

Hide file tree

Showing 14 changed files with 131 additions and 14 deletions.
diff --git a/doc/user_guide/coordinate_systems.rst b/doc/user_guide/coordinate_systems.rst
@@ -230,3 +230,13 @@ carried out through :meth:`boule.Ellipsoid.geodetic_to_spherical`:
     print("longitude:", longitude)
     print("spherical latitude:", sph_latitude)
     print("radius:", radius)
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <coordinate_systems>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <coordinate_systems>`
+        :text-align: center
diff --git a/doc/user_guide/equivalent_sources/block-averaged-eqs.rst b/doc/user_guide/equivalent_sources/block-averaged-eqs.rst
@@ -211,3 +211,12 @@ we are efectivelly upward continuing the data.
     fig.show()
 
 
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <block-averaged-eqs>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <block-averaged-eqs>`
+        :text-align: center
diff --git a/doc/user_guide/equivalent_sources/eq-sources-spherical.rst b/doc/user_guide/equivalent_sources/eq-sources-spherical.rst
@@ -183,4 +183,14 @@ Lets plot it:
     fig.coast(shorelines="0.5p,black", area_thresh=1e4)
     fig.colorbar(cmap=True, frame=["a50f25", "x+lmGal"])
 
-    fig.show()
+    fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <eq-sources-spherical>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <eq-sources-spherical>`
+        :text-align: center
diff --git a/doc/user_guide/equivalent_sources/eqs-parameters-estimation.rst b/doc/user_guide/equivalent_sources/eqs-parameters-estimation.rst
@@ -234,3 +234,13 @@ The best parameters not only produce a better score, but they also generate
 a visibly more accurate prediction. In the first plot the equivalent sources
 are so shallow that we can actually see the distribution of sources in the
 produced grid.
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <eqs-parameters-estimation>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <eqs-parameters-estimation>`
+        :text-align: center
diff --git a/doc/user_guide/equivalent_sources/gradient-boosted-eqs.rst b/doc/user_guide/equivalent_sources/gradient-boosted-eqs.rst
@@ -192,4 +192,12 @@ And plot it:
     fig.show()
 
 
+----
 
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <gradient-boosted-eqs>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <gradient-boosted-eqs>`
+        :text-align: center
diff --git a/doc/user_guide/equivalent_sources/index.rst b/doc/user_guide/equivalent_sources/index.rst
@@ -137,7 +137,7 @@ And plot it:
          cmap=True,
          style="c3p",
          projection=fig_proj,
-         region=region, 
+         region=region,
          frame=['ag', f"+t{title}"],
       )
    fig.colorbar(cmap=True, position="JMR", frame=["a50f25", "y+lmGal"])
@@ -151,7 +151,7 @@ And plot it:
          y=northing,
          color=data.gravity_disturbance_mgal,
          cmap=True,
-         style="c3p", 
+         style="c3p",
          frame=['ag', f"+t{title}"],
       )
    fig.colorbar(cmap=True, position="JMR", frame=["a50f25", "y+lmGal"])
@@ -199,3 +199,13 @@ And plot it
    fig.colorbar(cmap=True, frame=["a50f25", "x+lgravity disturbance", "y+lmGal"])
 
    fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <index>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <index>`
+        :text-align: center
diff --git a/doc/user_guide/forward_modelling/point.rst b/doc/user_guide/forward_modelling/point.rst
@@ -93,7 +93,7 @@ Lets plot this gravitational field:
 
 .. jupyter-execute::
 
-   import pygmt 
+   import pygmt
 
    grid = vd.make_xarray_grid(
       coordinates, g_z, data_names="g_z", extra_coords_names="extra")
@@ -220,7 +220,7 @@ Lets plot these results using :mod:`pygmt`:
 
 .. jupyter-execute::
 
-   import pygmt 
+   import pygmt
 
    grid = vd.make_xarray_grid(
       coordinates_spherical, g_z, data_names="g_z", extra_coords_names="extra")
@@ -236,6 +236,16 @@ Lets plot these results using :mod:`pygmt`:
       grid=grid.g_z,
       frame=[f"WSne+t{title}", "x", "y"],
       cmap=True,)
-      
+
    fig.colorbar(cmap=True, position="JMR", frame=["a0.000000005", "x+lmGal"])
    fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <point>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <point>`
+        :text-align: center
diff --git a/doc/user_guide/forward_modelling/prism.rst b/doc/user_guide/forward_modelling/prism.rst
@@ -206,3 +206,13 @@ Finally, lets plot the gravitational field:
       cmap='viridis',)
    fig.colorbar(cmap=True, position="JMR", frame=["a.02", "x+lmGal"])
    fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <prism>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <prism>`
+        :text-align: center
diff --git a/doc/user_guide/forward_modelling/tesseroid.rst b/doc/user_guide/forward_modelling/tesseroid.rst
@@ -98,7 +98,7 @@ And finally plot the computed gravitational field
 
 .. jupyter-execute::
 
-   import pygmt 
+   import pygmt
    grid = vd.make_xarray_grid(
       coordinates, gravity, data_names="gravity", extra_coords_names="extra")
 
@@ -256,4 +256,14 @@ Finally, lets plot it:
    fig.colorbar(cmap=True, frame=["a200f100", "x+lmGal"])
    fig.coast(shorelines="1p,black")
 
-   fig.show()
+   fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <tesseroid>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <tesseroid>`
+        :text-align: center
diff --git a/doc/user_guide/gravity_disturbance.rst b/doc/user_guide/gravity_disturbance.rst
@@ -148,3 +148,13 @@ And plot it:
 
 The gravity disturbances can be interpreted as the gravitational effect of
 every *anomalous mass*, i.e. that is not contained in the *normal Earth*.
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <gravity_disturbance>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <gravity_disturbance>`
+        :text-align: center
diff --git a/doc/user_guide/topographic_correction.rst b/doc/user_guide/topographic_correction.rst
@@ -67,7 +67,7 @@ And plot it:
       color=data.gravity_disturbance_mgal,
       cmap=True,
       style="c3p",
-      projection="M15c", 
+      projection="M15c",
       frame=['ag', 'WSen'],
    )
    fig.colorbar(cmap=True, frame=["a50f25", "x+lgravity disturbance", "y+lmGal"])
@@ -120,7 +120,7 @@ We can now compute the Bouguer disturbance and plot it:
       color=bouguer_disturbance,
       cmap=True,
       style="c3p",
-      projection="M15c", 
+      projection="M15c",
       frame=['ag', 'WSen'],
    )
    fig.colorbar(cmap=True, frame=["a50f25", "x+lBouguer disturbance (with simple Bouguer correction)", "y+lmGal"])
@@ -240,8 +240,18 @@ And plot it:
       color=topo_free_disturbance,
       cmap=True,
       style="c3p",
-      projection="M15c", 
+      projection="M15c",
       frame=['ag', 'WSen'],
    )
    fig.colorbar(cmap=True, frame=["a50f25", "x+lTopography-free gravity disturbance", "y+lmGal"])
-   fig.show()
+   fig.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <topographic_correction>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <topographic_correction>`
+        :text-align: center
diff --git a/doc/user_guide/transformations.rst b/doc/user_guide/transformations.rst
@@ -395,3 +395,13 @@ Let's plot the results side by side:
         pad=0.08,
     )
     plt.show()
+
+----
+
+.. grid:: 2
+
+    .. grid-item-card:: :jupyter-download-script:`Download Python script <transformations>`
+        :text-align: center
+
+    .. grid-item-card:: :jupyter-download-nb:`Download Jupyter notebook <transformations>`
+        :text-align: center
diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt
@@ -4,7 +4,7 @@ sphinx-book-theme==0.2.*
 sphinx-gallery==0.10.*
 sphinx-design==0.2.*
 sphinx-copybutton==0.5.*
-jupyter-sphinx==0.3.*
+jupyter-sphinx==0.4.*
 boule
 pyproj
 ensaio>=0.5.*

diff --git a/environment.yml b/environment.yml
@@ -32,7 +32,7 @@ dependencies:
   - sphinx-gallery==0.10.*
   - sphinx-design==0.2.*
   - sphinx-copybutton==0.5.*
-  - jupyter-sphinx==0.3.*
+  - jupyter-sphinx==0.4.*
   - pyproj
   - matplotlib
   - ensaio