Update example documentation and instructions (#216)

brycemines · web-flow · commit f5af90931d17 · 2025-09-14T17:17:28.000-06:00
* update mantaray readme

* fix: update example docs
diff --git a/README.md b/README.md
@@ -6,7 +6,19 @@
 
 A library for surface gravity waves ray tracing.
 
-![Demo](https://github.com/mines-oceanography/ray_tracing/blob/demo-animation/notebooks/canonical_examples/demo_animation.gif)
+![Demo](https://github.com/mines-oceanography/mantaray/blob/main/notebooks/canonical_examples/demo_animation.gif)
+
+## Examples
+The examples are located in the `notebooks` directory, and each scenario is inside its own subfolder.
+
+To run the example notebooks, follow [installation](#installation) instructions to install pixi and clone the repo. Then, install the examples environment using `pixi run -e examples develop`. 
+
+After that there are multiple options:
+- Follow our development [instructions](#using-jupyter-lab) for using jupyter lab.
+- Start a shell with the environment using the command `pixi shell -e examples`.
+- Find the installation inside the `.pixi` folder and run the examples your own way.
+
+If there are additional instructions, such as needing data files, they will be located in the readme of that example's folder.
 
 ## Development
 ### Installation
diff --git a/docs/gallery_header.rst b/docs/gallery_header.rst
@@ -1,15 +1,31 @@
 Notebook Gallery
 ================
 
+These notebooks contain examples of various use cases for mantaray.
+
+Each example is in its own folder. Many folders have more than one notebook, and some will require you to run a notebook that generates data first before running the ray tracing notebook. 
+
+To run the example notebooks, follow installation instructions in the readme to install pixi and clone the repo. Then, install the examples environment using `pixi run -e examples develop`. 
+
+After that there are multiple options:
+
+1. Follow our development instructions for using jupyter lab.
+
+2. Start a shell with the environment using the command `pixi shell -e examples`.
+
+3. Find the installation inside the `.pixi` folder and run the examples your own way.
+
+Any additional instructions, such as order of running notebooks or needing data files, will be located in the readme for that example in the `notebooks` folder of the repository.
+
 .. base-gallery::
     :caption: Gallery caption
     :tooltip:
 
-    tutorial
-    canonical_ray_tracing
     idealized_fields
-    snells_law_verification
-    data_generation
+    canonical_ray_tracing
     homepage_animation
+    data_generation
+    snells_law_verification
     agulhas_example
-    nazare_example
+    nazare_example
+    tutorial
diff --git a/notebooks/README.md b/notebooks/README.md
@@ -0,0 +1,14 @@
+# Notebooks
+
+These notebooks contain examples of various use cases for mantaray.
+
+Each example is in its own folder. Many folders have more than one notebook, and some will require you to run a notebook that generates data first before running the ray tracing notebook. 
+
+To run the example notebooks, follow [installation](#installation) instructions to install pixi and clone the repo. Then, install the examples environment using `pixi run -e examples develop`. 
+
+After that there are multiple options:
+- Follow our development [instructions](#using-jupyter-lab) for using jupyter lab.
+- Start a shell with the environment using the command `pixi shell -e examples`.
+- Find the installation inside the `.pixi` folder and run the examples your own way.
+
+Any additional instructions, such as order of running notebooks or needing data files, will be located in the readme of that example's folder.
diff --git a/notebooks/canonical_examples/README.md b/notebooks/canonical_examples/README.md
@@ -0,0 +1,9 @@
+# Ray tracing canonical examples
+
+This example includes ray tracing for jets, eddies, islands, and beaches.
+
+1. First run the `idealized_fields.ipynb` notebook to generate the data files required for this example.
+2. Run the `canonical_ray_tracing.ipynb` notebook for ray tracing output and explanation.
+3. `homepage_animation.ipynb` is a bonus file used to create the animation for the readme.
+
+Additional supporting functions are included in `utils.py`
diff --git a/notebooks/canonical_examples/canonical_ray_tracing.ipynb b/notebooks/canonical_examples/canonical_ray_tracing.ipynb
@@ -40,7 +40,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This notebook covers how to run Mantaray with the custom depth and current fields that were constructed in `idealized_fields.ipynb`. It is recommended that users run through this notebook first."
+    "This notebook covers how to run Mantaray with the custom depth and current fields that were constructed in `idealized_fields.ipynb`. Ensure you ran that notebook successfully and the forcing files appear in the `forcing/` directory relative to this file."
    ]
   },
   {
diff --git a/notebooks/theoretical_comparison/README.md b/notebooks/theoretical_comparison/README.md
@@ -0,0 +1,8 @@
+# Comparison of mantaray and theoretical solutions
+
+This example performs ray tracing on simple examples where the trajectory can be calculated analytically.
+
+1. First run all cells in `data_generation.ipynb` to generate data used in this example.
+2. Run `snells_law_verification.ipynb` for analytical ray tracing.
+
+Additional supporting functions are included in `support.py`.
diff --git a/notebooks/theoretical_comparison/data_generation.ipynb b/notebooks/theoretical_comparison/data_generation.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Notebook to Generate Bathymetry and Current Data for snells_law_verfication.ipynb\n",
+    "# Generate Bathymetry and Current Data for Analytical Comparisons\n",
     "\n",
     "This notebook generates current and bathymetry arrays that are used to run `snells_law_verification.ipynb`. Files are saved in netcdf3 classic format to the forcing subdirectory."
    ]
diff --git a/notebooks/tutorial/tutorial.ipynb b/notebooks/tutorial/tutorial.ipynb

Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@`
`40`	`40`	`"cell_type": "markdown",`
`41`	`41`	`"metadata": {},`
`42`	`42`	`"source": [`
`43`		- "This notebook covers how to run Mantaray with the custom depth and current fields that were constructed in `idealized_fields.ipynb`. It is recommended that users run through this notebook first."
	`43`	+ "This notebook covers how to run Mantaray with the custom depth and current fields that were constructed in `idealized_fields.ipynb`. Ensure you ran that notebook successfully and the forcing files appear in the `forcing/` directory relative to this file."
`44`	`44`	`]`
`45`	`45`	`},`
`46`	`46`	`{`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`	`"cell_type": "markdown",`
`5`	`5`	`"metadata": {},`
`6`	`6`	`"source": [`
`7`		`- "# Notebook to Generate Bathymetry and Current Data for snells_law_verfication.ipynb\n",`
	`7`	`+ "# Generate Bathymetry and Current Data for Analytical Comparisons\n",`
`8`	`8`	`"\n",`
`9`	`9`	"This notebook generates current and bathymetry arrays that are used to run `snells_law_verification.ipynb`. Files are saved in netcdf3 classic format to the forcing subdirectory."
`10`	`10`	`]`