fix suggestions from review and add emojis to notebook titles

reint-fischer · reint-fischer · commit 590bbe4fa0ac · 2025-12-09T13:23:05.000+01:00
diff --git a/docs/_static/concepts_diagram.png b/docs/_static/concepts_diagram.png
diff --git a/docs/_static/concepts_diagram.svg b/docs/_static/concepts_diagram.svg
diff --git a/docs/getting_started/explanation_concepts.md b/docs/getting_started/explanation_concepts.md
@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 ---
 
-# Parcels concepts
+# 📖 Parcels conceptual workflow
 
 Parcels is a set of Python classes and methods to create customisable particle tracking simulations using gridded output from (ocean) circulation models.
 
@@ -19,7 +19,7 @@ A Parcels simulation is generally built up from four different components:
 
 We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../user_guide/index.md) and more detailed _explanations_ of Parcels functionality are included under **"Read more about"** subsections. The full list of classes and methods is in the [API reference](../reference.md). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation.
 
-```{figure} ../_static/concepts_diagram.svg
+```{figure} ../_static/concepts_diagram.png
 :alt: Parcels concepts diagram
 :width: 100%
 
@@ -63,11 +63,11 @@ Each `parcels.Field` is defined on a grid. With Parcels, we can simulate particl
 
 To find the value of a `parcels.Field` at any particle location, Parcels interpolates the gridded field. Depending on the variable, grid, and required accuracy, different interpolation methods may be appropriate. Parcels comes with a number of built-in **`parcels.interpolators`**.
 
-### Read more about interpolation
+#### Read more about interpolation
 
 - [Interpolation explanation](../user_guide/examples/explanation_interpolation.md)
 
-### Learn how to use Parcels interpolators
+#### Learn how to use Parcels interpolators
 
 - [Interpolators guide](../user_guide/examples/tutorial_interpolation.ipynb)
 
@@ -86,7 +86,7 @@ lat = np.array([0])
 lon = np.array([0])
 
 # Create a ParticleSet
-pset = parcels.ParticleSet(fieldset, parcels.Particle, time, z, lat, lon)
+pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, time=time, z=z, lat=lat, lon=lon)
 ```
 
 ### Learn more about how to create ParticleSets
@@ -129,7 +129,7 @@ We can write custom kernels to add many different types of 'behaviour' to the pa
 ```python
 # Create a custom Particle object with an "age" variable
 CustomParticle =  parcels.Particle.add_variable(
-    parcels.Variable("age", initial=np.nan)
+    parcels.Variable("age", initial=0)
 )
 
 # Create a custom kernel which keeps track of the particle age
@@ -169,11 +169,11 @@ The execution of the simulation is done using the method **`parcels.ParticleSet.
 4. (Optional) The `ParticleFile` object to write the output to.
 
 ```python
-runtime = np.timedelta64(1, "D")
 dt = np.timedelta64(5, "m")
+runtime = np.timedelta64(1, "D")
 
 # Run the simulation
-pset.execute(kernels, runtime, dt)
+pset.execute(pyfunc=kernels, dt=dt, runtime=runtime)
 ```
 
 ### Output
@@ -184,5 +184,5 @@ There are many ways to analyze particle output, and although we provide [a short
 
 #### Learn how to run a simulation
 
-- [Choose an appropriate timestep](../user_guide/examples/tutorial_numerical_accuracy.ipynb)
+- [Choose an appropriate timestep and integrator](../user_guide/examples/tutorial_numerical_accuracy.ipynb)
 - [Work with Parcels output](./tutorial_output.ipynb)
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -5,9 +5,9 @@ Getting started with parcels is easy; here you will find:
 ```{toctree}
 :maxdepth: 1
 Installation guide <installation.md>
-Quickstart tutorial <tutorial_quickstart.md>
-Output tutorial <tutorial_output.ipynb>
-Concepts explanation <explanation_concepts.md>
+🎓 Quickstart tutorial <tutorial_quickstart.md>
+🎓 Output tutorial <tutorial_output.ipynb>
+📖 Conceptual workflow <explanation_concepts.md>
 ```
 
 ```{note}
diff --git a/docs/getting_started/tutorial_output.ipynb b/docs/getting_started/tutorial_output.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Working with Parcels output\n"
+    "# 🎓 Working with Parcels output"
    ]
   },
   {
diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md
@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 ---
 
-# Quickstart tutorial
+# 🎓 Quickstart tutorial
 
 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
diff --git a/docs/user_guide/examples/explanation_grids.md b/docs/user_guide/examples/explanation_grids.md
@@ -1,4 +1,4 @@
-# Grids
+# 📖 Grids
 
 Parcels `Field` objects exist on a (structured) `parcels.XGrid` or (unstructured) `parcels.Uxgrid`. Here we describe these grids on a conceptual level.
 
diff --git a/docs/user_guide/examples/explanation_interpolation.md b/docs/user_guide/examples/explanation_interpolation.md
@@ -1,4 +1,4 @@
-# Interpolators
+# 📖 Interpolators Overview and API
 
 Interpolation is an important functionality of Parcels. On this page we will discuss the way it is
 implemented in **Parcels** and how to write a custom interpolator function.
diff --git a/docs/user_guide/examples/explanation_kernelloop.md b/docs/user_guide/examples/explanation_kernelloop.md
@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 ---
 
-# The Parcels Kernel loop
+# 📖 The Parcels Kernel loop
 
 On this page we discuss Parcels' execution loop, and what happens under the hood when you combine multiple Kernels.
 
diff --git a/docs/user_guide/examples/tutorial_Argofloats.ipynb b/docs/user_guide/examples/tutorial_Argofloats.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Mimicking an Argo float"
+    "# 🖥️ Mimicking an Argo float"
    ]
   },
   {
diff --git a/docs/user_guide/examples/tutorial_delaystart.ipynb b/docs/user_guide/examples/tutorial_delaystart.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Delayed starts\n"
+    "# 🖥️ Delayed starts\n"
    ]
   },
   {
diff --git a/docs/user_guide/examples/tutorial_diffusion.ipynb b/docs/user_guide/examples/tutorial_diffusion.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Diffusion\n",
+    "# 🖥️ Diffusion\n",
     "\n",
     "In Eulerian ocean models, sub-grid scale dispersion of tracers such as heat, salt, or nutrients is often parameterized as a diffusive process. In Lagrangian particle simulations, sub-grid scale effects can be parameterized as a stochastic process, randomly displacing a particle position in proportion to the local eddy diffusivity ([Van Sebille et al. 2018](https://doi.org/10.1016/j.ocemod.2017.11.008)). Parameterizing sub-grid scale dispersion may be especially important when coarse velocity fields are used that do not resolve mesoscale eddies ([Shah et al., 2017](https://doi.org/10.1175/JPO-D-16-0098.1)). This tutorial explains how to use a sub-grid scale parameterization in _Parcels_ that is consistent with the advection-diffusion equation used in Eulerian models.\n",
     "\n",
diff --git a/docs/user_guide/examples/tutorial_gsw_density.ipynb b/docs/user_guide/examples/tutorial_gsw_density.ipynb
@@ -5,7 +5,7 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# Using the `gsw` toolbox to compute density"
+    "# 🖥️ Using the `gsw` toolbox to compute density"
    ]
   },
   {
diff --git a/docs/user_guide/examples/tutorial_interpolation.ipynb b/docs/user_guide/examples/tutorial_interpolation.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Using `parcels.interpolators`\n",
+    "# 🖥️ Using `parcels.interpolators`\n",
     "Parcels comes with a number of different interpolation methods for tracer fields, such as temperature. Here, we will look at a few common `parcels.interpolators` for structured (`X`) grids, and how to configure them in an idealised example. For more guidance on the sampling of such fields, check out the [sampling tutorial](./tutorial_sampling).\n",
     "\n",
     "We first import the relevant modules"
diff --git a/docs/user_guide/examples/tutorial_nemo_curvilinear.ipynb b/docs/user_guide/examples/tutorial_nemo_curvilinear.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Curvilinear grids\n"
+    "# 🖥️ Curvilinear grids"
    ]
   },
   {
diff --git a/docs/user_guide/examples/tutorial_numerical_accuracy.ipynb b/docs/user_guide/examples/tutorial_numerical_accuracy.ipynb
@@ -5,7 +5,7 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# Set up an efficient and accurate simulation\n",
+    "# 🖥️ Choosing an appropriate timestep and integrator \n",
     "\n",
     "```{note}\n",
     "TODO: write notebook describing how to use `dt` and integration methods in Kernels to control numerical accuracy. Use [Michaels tutorial](https://github.com/Parcels-code/10year-anniversary-session2/blob/main/advection_and_windage.ipynb) as a starting point.\n",
diff --git a/docs/user_guide/examples/tutorial_sampling.ipynb b/docs/user_guide/examples/tutorial_sampling.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Sampling a Field\n",
+    "# 🖥️ Sampling a Field\n",
     "The particle trajectories allow us to study fields like temperature, plastic concentration or chlorophyll from a Lagrangian perspective.\n",
     "\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",
diff --git a/docs/user_guide/examples/tutorial_statuscodes.md b/docs/user_guide/examples/tutorial_statuscodes.md
@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 ---
 
-# Working with Status Codes
+# 🖥️ Working with Status Codes
 
 In order to capture errors in the [Kernel loop](explanation_kernelloop.md), Parcels uses a Status Code system. There are several Status Codes, listed below.
 
diff --git a/docs/user_guide/examples/tutorial_unitconverters.ipynb b/docs/user_guide/examples/tutorial_unitconverters.ipynb
@@ -5,7 +5,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Spherical grids and unit converters\n"
+    "# 🖥️ Spherical grids and unit converters"
    ]
   },
   {
diff --git a/docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb b/docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md

Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`"cell_type": "markdown",`
`6`	`6`	`"metadata": {},`
`7`	`7`	`"source": [`
`8`		`- "# Working with Parcels output\n"`
	`8`	`+ "# 🎓 Working with Parcels output"`
`9`	`9`	`]`
`10`	`10`	`},`
`11`	`11`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Grids`
	`1`	`+# 📖 Grids`
`2`	`2`
`3`	`3`	Parcels `Field` objects exist on a (structured) `parcels.XGrid` or (unstructured) `parcels.Uxgrid`. Here we describe these grids on a conceptual level.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Interpolators`
	`1`	`+# 📖 Interpolators Overview and API`
`2`	`2`
`3`	`3`	`Interpolation is an important functionality of Parcels. On this page we will discuss the way it is`
`4`	`4`	`implemented in Parcels and how to write a custom interpolator function.`