Implement MyST-NB to run notebooks in docs

.gitignore

@@ -1,6 +1,7 @@
 build/*
 docs/_build/*
 docs/_downloads
+docs/jupyter_execute/*
 output
 
 *.log

docs/conf.py

@@ -36,8 +36,7 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
-    "myst_parser",
-    "nbsphinx",
+    "myst_nb",
     "numpydoc",
     "sphinxcontrib.mermaid",
     "sphinx_design",
@@ -114,7 +113,13 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build", "**.ipynb_checkpoints", "user_guide/examples_v3"]
+exclude_patterns = [
+    "_build",
+    "jupyter_execute",
+    "**.ipynb_checkpoints",
+    "user_guide/examples_v3",
+]
+nb_execution_excludepatterns = ["jupyter_execute"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/development/docsguide.md

@@ -17,4 +17,7 @@ TODO: outline functions of the documentation based on resources
 
 ## Style guide
 
-- Write documentation in first person plural ("we"). In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels.
+- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are part of Parcels. If we use `from parcels import class`, the use of `class` in a cell further along is not obviously part of `parcels`.
+- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because we want users to see where in the simulation setup things change. We try to limit each page in the documentation to a small number of examples.
+- **Import packages at the top of the section in which they are first used** to show what they are used for.
+- **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you". Please refrain from using impersonal subjects such as "the user".

docs/getting_started/tutorial_quickstart.md

@@ -1,3 +1,81 @@
-# Quickstart tutorial"
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
 
-TODO: Completely rewrite examples/parcels_tutorial.ipynb into the quickstart tutorial. Decide which file format and notebook testing to do so this file is checked, which is not in the "examples" folder
+# Quickstart tutorial
+
+```{note}
+TODO: Completely rewrite examples/parcels_tutorial.ipynb to be this quickstart tutorial. Decide which file format and notebook testing to do so this file is checked, which is not in the "examples" folder
+```
+
+Welcome to the **Parcels** quickstart tutorial, in which we will go through all the necessary steps to run a simulation. The code in this notebook can be used as a starting point to run Parcels in your own environment. Along the way we will familiarize ourselves with some specific classes and methods. If you are ever confused about one of these, or how they relate to each other, we have a [concepts overview](concepts_overview.md) to describe how we think about them. Let's dive in!
+
+## Import
+
+```{code-cell}
+import numpy as np
+import xarray as xr
+import parcels
+```
+
+## Input: `FieldSet`
+
+Load the CopernicusMarine data in the Agulhas region from the example_datasets
+
+```{code-cell}
+example_dataset_folder = parcels.download_example_dataset(
+    "CopernicusMarine_data_for_Argo_tutorial"
+)
+
+ds = xr.open_mfdataset(f"{example_dataset_folder}/*.nc", combine="by_coords")
+ds.load()  # load the dataset into memory
+
+fieldset = parcels.FieldSet.from_copernicusmarine(ds)
+```
+
+## Input: `ParticleSet`
+
+```{code-cell}
+# Particle locations and initial time
+npart = 10  # number of particles to be released
+lon = np.repeat(32, npart)
+lat = np.linspace(-32.5, -30.5, npart)
+time = np.repeat(ds.time.values[0], npart)
+z = np.repeat(ds.depth.values[0], npart)
+
+pset = parcels.ParticleSet(
+    fieldset=fieldset, pclass=parcels.Particle, lon=lon, lat=lat, time=time, z=z
+)
+```
+
+## Compute: `Kernel`
+
+```{code-cell}
+kernels = parcels.kernels.AdvectionEE
+```
+
+## Prepare output: `ParticleFile`
+
+```{code-cell}
+output_file = parcels.ParticleFile("Output.zarr", outputdt=np.timedelta64(1, "h"))
+```
+
+## Run Simulation: `ParticleSet.execute()`
+
+```{code-cell}
+pset.execute(
+    kernels,
+    runtime=np.timedelta64(5, "h"),
+    dt=np.timedelta64(5, "m"),
+    output_file=output_file,
+)
+```
+
+## Read output
+
+```{code-cell}
+data_xarray = xr.open_zarr("Output.zarr")
+data_xarray
+```

docs/index.md

@@ -8,8 +8,6 @@ Welcome to the documentation of Parcels. **Parcels** provides a set of Python cl
 
 _Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the_ [NEMO Ocean Model](https://www.nemo-ocean.eu/).
 
-**Version**: {{env.config.version}}
-
 ```{note}
 You can browse the documentation for older versions by using the version switcher in the bottom right.
 ```

docs/user_guide/examples/tutorial_output.ipynb

@@ -15,11 +15,11 @@
    "source": [
     "This tutorial covers the format of the trajectory output exported by Parcels. **Parcels does not include advanced analysis or plotting functionality**, which users are suggested to write themselves to suit their research goals. Here we provide some starting points to explore the parcels output files yourself.\n",
     "\n",
-    "- [**Reading the output file**](#Reading-the-output-file)\n",
-    "- [**Trajectory data structure**](#Trajectory-data-structure)\n",
-    "- [**Analysis**](#Analysis)\n",
-    "- [**Plotting**](#Plotting)\n",
-    "- [**Animations**](#Animations)\n",
+    "- [**Reading the output file**](#reading-the-output-file)\n",
+    "- [**Trajectory data structure**](#trajectory-data-structure)\n",
+    "- [**Analysis**](#analysis)\n",
+    "- [**Plotting**](#plotting)\n",
+    "- [**Animations**](#animations)\n",
     "\n",
     "For more advanced reading and tutorials on the analysis of Lagrangian trajectories, we recommend checking out the [Lagrangian Diagnostics Analysis Cookbook](https://lagrangian-diags.readthedocs.io/en/latest/tutorials.html) and the project in general. The [TrajAn package](https://opendrift.github.io/trajan/index.html) can be used to read and plot datasets of Lagrangian trajectories."
    ]
@@ -373,7 +373,7 @@
    "source": [
     "Trajectory plots like the ones above can become very cluttered for large sets of particles. To better see patterns, it's a good idea to create an animation in time and space. To do this, matplotlib offers an [animation package](https://matplotlib.org/stable/api/animation_api.html). Here we show how to use the [**FuncAnimation**](https://matplotlib.org/3.3.2/api/_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation) class to animate parcels trajectory data, based on [this visualisation tutorial](https://github.com/Parcels-code/10year-anniversary-session5/blob/eaf7ac35f43c222280fa5577858be81dc346c06b/animations_tutorial.ipynb) from 10-years Parcels. \n",
     "\n",
-    "To correctly reveal the patterns in time we must remember that the `obs` dimension does not necessarily correspond to the `time` variable ([see the section of Trajectory data structure above](#Trajectory-data-structure)). In the animation of the particles, we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#Conditional-selection) in each rendering.\n"
+    "To correctly reveal the patterns in time we must remember that the `obs` dimension does not necessarily correspond to the `time` variable ([see the section of Trajectory data structure above](#trajectory-data-structure)). In the animation of the particles, we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#conditional-selection) in each rendering.\n"
    ]
   },
   {

docs/user_guide/examples/tutorial_sampling.ipynb

@@ -17,17 +17,17 @@
     "\n",
     "In this tutorial we will go through how particles can sample `Fields`, using temperature as an example. Along the way we will get to know the parcels class `Variable` (see [here](https://parcels.readthedocs.io/en/latest/reference/particles.html#parcels.particle.Variable) for the documentation) and some of its methods. This tutorial covers several applications of a sampling setup:\n",
     "\n",
-    "- [**Basic along trajectory sampling**](#Basic-sampling)\n",
-    "- [**Sampling velocity fields**](#Sampling-velocity-fields)\n",
-    "- [**Sampling initial conditions**](#Sampling-initial-values)\n"
+    "- [**Basic along trajectory sampling**](#basic-sampling)\n",
+    "- [**Sampling velocity fields**](#sampling-velocity-fields)\n",
+    "- [**Sampling initial conditions**](#sampling-initial-values)\n"
    ]
   },
   {
    "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Basic sampling\n",
+    "### Basic sampling\n",
     "\n",
     "We import both the packages that we need to set up the simulation, as well as the parcels package.\n"
    ]
@@ -206,7 +206,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Sampling velocity fields\n"
+    "# Sampling velocity fields\n"
    ]
   },
   {
@@ -304,7 +304,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Sampling initial values\n"
+    "# Sampling initial values\n"
    ]
   },
   {

docs/user_guide/examples_v3/parcels_tutorial.ipynb

@@ -965,7 +965,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "parcels",
+   "display_name": "test-notebooks",
    "language": "python",
    "name": "python3"
   },
@@ -979,7 +979,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.11.0"
   }
  },
  "nbformat": 4,

docs/user_guide/index.md

@@ -9,22 +9,24 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4.
 
 ## Getting started
 
-```{nbgallery}
+<!-- ```{nbgallery}
 :caption: Getting started
 :name: tutorial-overview
 
 <!-- examples/tutorial_parcels_structure.ipynb -->
 <!-- examples/parcels_tutorial.ipynb -->
+
 examples/tutorial_output.ipynb
-```
+
+````-->
 
 ## How to:
 
 ```{note}
 **Migrate from v3 to v4** using [this migration guide](v4-migration.md)
-```
+````
 
-```{nbgallery}
+<!-- ```{nbgallery}
 :caption: Set up FieldSets
 :name: tutorial-fieldsets
 
@@ -36,16 +38,17 @@ examples/tutorial_output.ipynb
 <!-- examples/tutorial_periodic_boundaries.ipynb -->
 <!-- examples/tutorial_interpolation.ipynb -->
 <!-- examples/tutorial_unitconverters.ipynb -->
-```
 
-```{nbgallery}
+````-->
+
+<!-- ```{nbgallery}
 :caption: Create ParticleSets
 :name: tutorial-particlesets
 
 examples/tutorial_delaystart.ipynb
-```
+``` -->
 
-```{nbgallery}
+<!-- ```{nbgallery}
 :caption: Write a custom kernel
 :name: tutorial-kernels
 
@@ -56,9 +59,9 @@ examples/tutorial_gsw_density.ipynb
 <!-- examples/tutorial_interaction.ipynb -->
 <!-- examples/tutorial_analyticaladvection.ipynb -->
 <!-- examples/tutorial_kernelloop.ipynb -->
-```
+``` -->
 
-```{nbgallery}
+<!-- ```{nbgallery}
 :caption: Other tutorials
 :name: tutorial-other
 
@@ -69,18 +72,18 @@ examples/tutorial_gsw_density.ipynb
 <!-- examples/documentation_LargeRunsOutput.ipynb -->
 <!-- examples/documentation_geospatial.ipynb -->
 <!-- examples/documentation_advanced_zarr.ipynb -->
-```
+``` -->
 
-```{nbgallery}
+<!-- ```{nbgallery}
 :caption: Worked examples
 :name: tutorial-examples
 
 examples/tutorial_Argofloats.ipynb
 <!-- examples/documentation_homepage_animation.ipynb -->
-```
+``` -->
 
 ```{toctree}
 :hidden:
 v3 to v4 migration guide <v4-migration>
 Example scripts <additional_examples>
-```
+````

pixi.toml

@@ -83,13 +83,12 @@ gsw = "*"
 
 [feature.docs.dependencies]
 numpydoc = "!=1.9.0"
-nbsphinx = "*"
+myst-nb = "*"
 ipython = "*"
 sphinx = "*"
 pandoc = "*"
 pydata-sphinx-theme = "*"
 sphinx-autobuild = "*"
-myst-parser = "*"
 sphinxcontrib-mermaid = "*"
 sphinx-design = "*"