Merge pull request #411 from fsenf/rtd-integration-of-notebooks

Readthedocs integration of notebooks
tobac-project · Mar 6, 2024 · adf125a · adf125a
2 parents cb44192 + df86e7f
commit adf125a
Show file tree

Hide file tree

Showing 14 changed files with 562 additions and 205 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -19,13 +19,14 @@
     "sphinx_rtd_theme",
     "sphinx.ext.napoleon",
     "nbsphinx",
+   "sphinx_gallery.load_style",
 ]
 
 
 html_theme = "sphinx_rtd_theme"
 
 html_static_path = ["_static"]
-
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 project = "tobac"
 

diff --git a/doc/examples.rst b/doc/examples.rst
@@ -1,16 +1,35 @@
-Example notebooks
-=================
+Example Gallery
+===============
 tobac is provided with a set of Jupyter notebooks that show examples of the application of tobac for different types of datasets.
 
-The notebooks can be found in the **examples** folder in the the repository. The necessary input data for these examples is avaliable on zenodo:
-www.zenodo.org/...
-and can be downloaded automatically by the Jupyter notebooks.
 
-The examples currently include four different applications of tobac:
-1. Tracking of scattered convection based on vertical velocity and condensate mixing ratio for 3D cloud-resolving model output.
-2. Tracking of scattered convection based on surface precipitation from the same cloud-resolving model output
-3. Tracking of convective clouds based on outgoing longwave radiation (OLR) for convection-permitting model simulation output
-4. Tracking of convective clouds based on OLR in geostationary satellite retrievals.
+.. nbgallery::
+   :caption: Fundamentals of Detection and Tracking
+
+   Test Blob in 2D <examples4doc/Basics/Idealized-Case-1_Tracking-of-a-Test-Blob-in-2D>
+   Two crossing Blobs <examples4doc/Basics/Idealized-Case-2_Two_crossing_Blobs.ipynb>
+
+   On Feature Detection: Part 1 <examples4doc/Basics/Methods-and-Parameters-for-Feature-Detection_Part_1.ipynb> 
+   On Feature Detection: Part 2 <examples4doc/Basics/Methods-and-Parameters-for-Feature-Detection_Part_2.ipynb>
+   On Segmentation <examples4doc/Basics/Methods-and-Parameters-for-Segmentation.ipynb>
+   On Linking <examples4doc/Basics/Methods-and-Parameters-for-Linking.ipynb>  
 
-The examples are based on the analyses presented in an article describing tobac that has been submitted to the journal GMD (Geophysical model development).
 
+
+
+.. nbgallery::
+   :caption: Examples of Using *tobac* with Observations
+
+   OLR from GOES-13 Satellite <examples4doc/Example_OLR_Tracking_satellite/Example_OLR_Tracking_satellite>
+   Combine Radar & Satellite <examples4doc/Example_Track_on_Radar_Segment_on_Satellite/Example_Track_on_Radar_Segment_on_Satellite>
+
+
+.. nbgallery::
+   :caption: Examples of Using *tobac* with Model Data
+
+   WRF OLR <examples4doc/Example_OLR_Tracking_model/Example_OLR_Tracking_model>
+   WRF Precip <examples4doc/Example_Precip_Tracking/Example_Precip_Tracking>
+   WRF Updrafts <examples4doc/Example_Updraft_Tracking/Example_Updraft_Tracking>
+   WRF Mesoscale Vorticity <examples4doc/Example_vorticity_tracking_model/Example_vorticity_tracking_model> 
+
+The notebooks can be found in the **examples** folder as part of the python package. The necessary input data for these examples is avaliable on zenodo and can be downloaded automatically by the Jupyter notebooks.
diff --git a/doc/examples4doc b/doc/examples4doc
@@ -0,0 +1 @@
+../examples
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -2,3 +2,4 @@ ipykernel
 nbsphinx
 numpy
 sphinx_rtd_theme
+sphinx-gallery
diff --git a/examples/Basics/Idealized-Case-1_Tracking-of-a-Test-Blob-in-2D.ipynb b/examples/Basics/Idealized-Case-1_Tracking-of-a-Test-Blob-in-2D.ipynb
@@ -3660,7 +3660,10 @@
      "iopub.status.busy": "2024-02-17T12:47:08.172748Z",
      "iopub.status.idle": "2024-02-17T12:47:09.791381Z",
      "shell.execute_reply": "2024-02-17T12:47:09.790072Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Basics/Idealized-Case-2_Two_crossing_Blobs.ipynb b/examples/Basics/Idealized-Case-2_Two_crossing_Blobs.ipynb
@@ -1529,7 +1529,10 @@
      "iopub.status.busy": "2024-02-17T12:48:25.308400Z",
      "iopub.status.idle": "2024-02-17T12:48:26.042068Z",
      "shell.execute_reply": "2024-02-17T12:48:26.040891Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Basics/Methods-and-Parameters-for-Feature-Detection_Part_1.ipynb b/examples/Basics/Methods-and-Parameters-for-Feature-Detection_Part_1.ipynb
@@ -934,7 +934,10 @@
      "iopub.status.busy": "2024-02-17T12:49:38.727101Z",
      "iopub.status.idle": "2024-02-17T12:49:39.336094Z",
      "shell.execute_reply": "2024-02-17T12:49:39.331074Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Basics/Methods-and-Parameters-for-Feature-Detection_Part_2.ipynb b/examples/Basics/Methods-and-Parameters-for-Feature-Detection_Part_2.ipynb
@@ -166,7 +166,10 @@
      "iopub.status.busy": "2024-02-17T12:48:42.120210Z",
      "iopub.status.idle": "2024-02-17T12:48:43.033618Z",
      "shell.execute_reply": "2024-02-17T12:48:43.031559Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Basics/Methods-and-Parameters-for-Linking.ipynb b/examples/Basics/Methods-and-Parameters-for-Linking.ipynb
@@ -950,7 +950,10 @@
      "iopub.status.busy": "2024-02-17T12:47:43.823635Z",
      "iopub.status.idle": "2024-02-17T12:47:45.019125Z",
      "shell.execute_reply": "2024-02-17T12:47:45.018445Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Basics/Methods-and-Parameters-for-Segmentation.ipynb b/examples/Basics/Methods-and-Parameters-for-Segmentation.ipynb
@@ -636,7 +636,10 @@
      "iopub.status.busy": "2024-02-17T12:49:18.942104Z",
      "iopub.status.idle": "2024-02-17T12:49:19.618526Z",
      "shell.execute_reply": "2024-02-17T12:49:19.617877Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Example_OLR_Tracking_model/Example_OLR_Tracking_model.ipynb b/examples/Example_OLR_Tracking_model/Example_OLR_Tracking_model.ipynb
@@ -426,7 +426,10 @@
      "iopub.status.busy": "2024-02-17T12:52:54.039750Z",
      "iopub.status.idle": "2024-02-17T12:53:43.162744Z",
      "shell.execute_reply": "2024-02-17T12:53:43.161536Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/...ple_Track_on_Radar_Segment_on_Satellite/Example_Track_on_Radar_Segment_on_Satellite.ipynb b/...ple_Track_on_Radar_Segment_on_Satellite/Example_Track_on_Radar_Segment_on_Satellite.ipynb
diff --git a/examples/Example_Updraft_Tracking/Example_Updraft_Tracking.ipynb b/examples/Example_Updraft_Tracking/Example_Updraft_Tracking.ipynb
@@ -857,7 +857,10 @@
      "iopub.status.busy": "2024-02-17T13:05:25.867849Z",
      "iopub.status.idle": "2024-02-17T13:05:56.448652Z",
      "shell.execute_reply": "2024-02-17T13:05:56.447922Z"
-    }
+    },
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
    },
    "outputs": [
     {

diff --git a/examples/Example_vorticity_tracking_model/Example_vorticity_tracking_model.ipynb b/examples/Example_vorticity_tracking_model/Example_vorticity_tracking_model.ipynb