[DOCS] Cleaning up the User Guide (#2737)

* Adding Headers to User guide

So that sections can directly be linked to

* Moving getting-started to within user-guide

* Updating links

* Update installation instructions

* Clean up docs

* Removing stray print statement in unit tests

* Fix info on combining models

Author: erikvansebille

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.bd-article .toctree-wrapper > p.caption {
+  display: none;
+}

docs/conf.py

@@ -187,6 +187,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 html_theme_options = {
     "logo": {
         "alt_text": "Parcels - Home",

docs/getting_started/index.md

@@ -12,7 +12,9 @@ _Animation of virtual particles carried by ocean surface flow in the global ocea
 You can browse the documentation for older versions by using the version switcher in the bottom right.
 ```
 
-**Useful links**: [Installation instructions](getting_started/installation.md) | [Discussions on GitHub](https://github.com/Parcels-code/parcels/discussions) | [Issue on GitHub](https://github.com/Parcels-code/parcels/issues) | [Parcels website](https://parcels-code.org/) | [CLAM community website](https://clam-community.github.io/) | [API reference](reference/parcels/index)
+**Useful links**: [Installation instructions](user_guide/getting_started/installation) | [Discussions on GitHub](https://github.com/Parcels-code/parcels/discussions) | [Issue on GitHub](https://github.com/Parcels-code/parcels/issues) | [Parcels website](https://parcels-code.org/) | [CLAM community website](https://clam-community.github.io/) | [API reference](reference/parcels/index)
+
+New to **Parcels**? Check out the [installation instructions](user_guide/getting_started/installation), run the [quickstart tutorial](user_guide/getting_started/tutorial_quickstart), and learn the [key concepts](user_guide/getting_started/explanation_concepts) to understand the package.
 
 `````{grid} 1 2 2 2
 :gutter: 4
@@ -22,13 +24,12 @@ You can browse the documentation for older versions by using the version switche
 ````{grid-item-card} Getting started
 :shadow: md
 
-New to **Parcels**? Check out the installation guide, run the quickstart tutorial, and learn the key concepts to understand the package.
+New to **Parcels**? Check out the [installation instructions](user_guide/getting_started/installation), run the [quickstart tutorial](user_guide/getting_started/tutorial_quickstart), and learn the [key concepts](user_guide/getting_started/explanation_concepts) to understand the package.
 
 +++
 
-```{button-ref} getting_started/index
+```{button-ref} user_guide/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -38,13 +39,12 @@ Get started!
 ````{grid-item-card} How to?
 :shadow: md
 
-Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and explainers to these and other questions here:
+Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and explainers to these and other questions here.
 
 +++
 
 ```{button-ref} user_guide/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -60,7 +60,6 @@ We encourage anyone to help improve **Parcels**: read our guidelines to get star
 
 ```{button-ref} development/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -76,7 +75,6 @@ Want to interact with other users and **Parcels** developers?
 
 ```{button-ref} community/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -95,6 +93,5 @@ User guide <user_guide/index>
 Community <community/index>
 Development <development/index>
 API reference <reference/parcels/index>
-v4 <v4/index>
 Parcels website <https://parcels-code.org/>
 ```

docs/index.md

@@ -18,7 +18,7 @@
     "3. Build a `FieldSet` with `parcels.FieldSet.from_ugrid_conventions`.\n",
     "4. Run the simulation as on any structured grid.\n",
     "\n",
-    "If you have not done so already, work through the [quickstart tutorial](../../getting_started/tutorial_quickstart.md) first to get familiar with `ParticleSet`, `Kernel`, and `ParticleFile`."
+    "If you have not done so already, work through the [quickstart tutorial](../getting_started/tutorial_quickstart.md) first to get familiar with `ParticleSet`, `Kernel`, and `ParticleFile`."
    ]
   },
   {
@@ -44,7 +44,7 @@
    "source": [
     "## Get the FESOM tutorial dataset\n",
     "\n",
-    "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. As in the [quickstart](../../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset` downloads the files into a local cache on first use; subsequent calls just return the cached copy.\n",
+    "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. As in the [quickstart](../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset` downloads the files into a local cache on first use; subsequent calls just return the cached copy.\n",
     "\n",
     "`uxarray` expects file paths rather than an in-memory dataset, so we trigger the downloads and then point `ux.open_mfdataset` at the cached files:"
    ]

docs/user_guide/examples/tutorial_fesom.ipynb

@@ -31,7 +31,7 @@
     "   end up below the local bathymetry and stop advecting them.\n",
     "\n",
     "If you have not done so already, work through the\n",
-    "[quickstart tutorial](../../getting_started/tutorial_quickstart.md) first to get familiar with\n",
+    "[quickstart tutorial](../getting_started/tutorial_quickstart.md) first to get familiar with\n",
     "`ParticleSet`, `Kernel`, and `ParticleFile`."
    ]
   },
@@ -66,7 +66,7 @@
     "* `horizontalVelX`, `horizontalVelY`: the 3D horizontal velocity components, defined at the mesh nodes\n",
     "  over 32 vertical layers.\n",
     "\n",
-    "As in the [quickstart](../../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset`\n",
+    "As in the [quickstart](../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset`\n",
     "downloads the files into a local cache on first use (subsequent calls return the cached copy) and opens\n",
     "them as `xarray` datasets:"
    ]

docs/user_guide/examples/tutorial_schism.ipynb

@@ -19,7 +19,7 @@
     "\n",
     "For these cases, you can use the `pfile.write()` method anywhere in a `Kernel`. You can write to the same file as the one specified in `output_file` or to a different file. \n",
     "\n",
-    "This short tutorial will show you how to use `pfile.write()` in a kernel. We will use the same dataset and particle set as in the [output tutorial ](../../getting_started/tutorial_output.ipynb)."
+    "This short tutorial will show you how to use `pfile.write()` in a kernel. We will use the same dataset and particle set as in the [output tutorial ](../getting_started/tutorial_output.ipynb)."
    ]
   },
   {

docs/user_guide/examples/tutorial_write_in_kernel.ipynb

@@ -17,9 +17,9 @@ A Parcels simulation is generally built up from four different components:
 3. [**Kernels**](#3-kernels). Kernels perform some specific operation on the particles every time step (e.g. advect the particles with the three-dimensional flow; or interpolate the temperature field to the particle location).
 4. [**Execute**](#4-execute). Execute the simulation. The core method which integrates the operations defined in Kernels for a given runtime and timestep, and writes output to a ParticleFile.
 
-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/parcels/index). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation.
+We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../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/parcels/index). 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.png
+```{figure} ../../_static/concepts_diagram.png
 :alt: Parcels concepts diagram
 :width: 100%
 
@@ -41,16 +41,13 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields)
 fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset)
 ```
 
-In some cases, we might want to combine `parcels.Field`s from different sources in the same `parcels.FieldSet`, such as ocean currents from one dataset and Stokes drift from another. This is possible in Parcels by adding each `parcels.Field` separately:
+In some cases, we might want to combine fields from different sources in the same `parcels.FieldSet`, such as ocean currents from one dataset and Stokes drift from another. This is possible in Parcels by creating multiple `parcels.FieldSet` objects and combining them into a single `parcels.FieldSet`:
 
 ```python
-dataset1 = xr.dataset("insert_current_data_files.nc")
 dataset2 = xr.dataset("insert_stokes_data_files.nc")
-
-Ucurrent = parcels.Field(name="Ucurrent", data=dataset1["Ucurrent"], grid=parcels.XGrid.from_dataset(dataset1), interp_method=parcels.interpolators.XLinear)
-Ustokes = parcels.Field(name="Ustokes", data=dataset2["Ustokes"], grid=parcels.XGrid.from_dataset(dataset2), interp_method=parcels.interpolators.XLinear)
-
-fieldset = parcels.FieldSet([Ucurrent, Ustokes])
+fields2 = {"Ustokes": ds_fields["ustokes"], "Vstokes": ds_fields["vstokes"]}
+ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields2)
+fieldset += parcels.FieldSet.from_sgrid_conventions(ds_fset, vector_fields={"UVstokes": ["Ustokes", "Vstokes"]})
 ```
 
 ### Grid
@@ -59,7 +56,7 @@ Each `parcels.Field` is defined on a grid. With Parcels, we can simulate particl
 
 ```{admonition} 📖 Read more about grids
 :class: seealso
-- [Grids explanation](../user_guide/examples/explanation_grids.md)
+- [Grids explanation](../examples/explanation_grids.md)
 ```
 
 ### Interpolation
@@ -68,12 +65,12 @@ To find the value of a `parcels.Field` at any particle location, Parcels interpo
 
 ```{admonition} 📖 Read more about interpolation
 :class: seealso
-- [Interpolation explanation](../user_guide/examples/explanation_interpolation.md)
+- [Interpolation explanation](../examples/explanation_interpolation.md)
 ```
 
 ```{admonition} 🖥️ Learn how to use Parcels interpolators
 :class: seealso
-- [Interpolators guide](../user_guide/examples/tutorial_interpolation.ipynb)
+- [Interpolators guide](../examples/tutorial_interpolation.ipynb)
 ```
 
 ## 2. ParticleSet
@@ -96,7 +93,7 @@ pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, t=t, z=z,
 
 ```{admonition} 🖥️ Learn more about how to create ParticleSets
 :class: seealso
-- [Release particles at different times](../user_guide/examples/tutorial_delaystart.ipynb)
+- [Release particles at different times](../examples/tutorial_delaystart.ipynb)
 ```
 
 ## 3. Kernels
@@ -126,7 +123,7 @@ def AdvectionEE(particles, fieldset):
 Basic kernels are included in Parcels to compute advection and diffusion. The standard advection kernel is `parcels.kernels.AdvectionRK2`, a [second-order Runge-Kutta integrator](https://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_methods#The_Runge%E2%80%93Kutta_method) of the advection function.
 
 ```{warning}
-It is advised _not_ to update the particle coordinates (`particles.t`, `particles.z`, `particles.y`, or `particles.x`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dy`, `particles.dx` and/or `particles.dz`. Read the [kernel loop tutorial](../user_guide/examples/explanation_kernelloop.md) to understand why.
+It is advised _not_ to update the particle coordinates (`particles.t`, `particles.z`, `particles.y`, or `particles.x`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dy`, `particles.dx` and/or `particles.dz`. Read the [kernel loop tutorial](../examples/explanation_kernelloop.md) to understand why.
 ```
 
 (custom-kernel)=
@@ -151,20 +148,20 @@ Every Kernel must be a function with the following (and only those) arguments: `
 ```
 
 ```{warning}
-We have to be careful with kernels that sample velocities on "spherical" grids (so with longitude and latitude in degrees). Parcels can automatically convert velocities from m s<sup>-1</sup> to degrees s<sup>-1</sup>, but only when using `VectorFields`. [This guide](../user_guide/examples/tutorial_velocityconversion.ipynb) describes how to use velocities on a "spherical" grid in Parcels.
+We have to be careful with kernels that sample velocities on "spherical" grids (so with longitude and latitude in degrees). Parcels can automatically convert velocities from m s<sup>-1</sup> to degrees s<sup>-1</sup>, but only when using `VectorFields`. [This guide](../examples/tutorial_velocityconversion.ipynb) describes how to use velocities on a "spherical" grid in Parcels.
 ```
 
 ```{admonition} 📖 Read more about the Kernel loop
 :class: seealso
-- [The Kernel loop](../user_guide/examples/explanation_kernelloop.md)
+- [The Kernel loop](../examples/explanation_kernelloop.md)
 ```
 
 ```{admonition} 🖥️ Learn how to write Kernels
 :class: seealso
-- [Sample fields like temperature](../user_guide/examples/tutorial_sampling.ipynb).
-- [Mimic the behaviour of ARGO floats](../user_guide/examples/tutorial_Argofloats.ipynb).
-- [Add diffusion to approximate subgrid-scale processes and unresolved physics](../user_guide/examples/tutorial_diffusion.ipynb).
-- [Convert velocities between units in m s<sup>-1</sup> and degrees s<sup>-1</sup>](../user_guide/examples/tutorial_velocityconversion.ipynb).
+- [Sample fields like temperature](../examples/tutorial_sampling.ipynb).
+- [Mimic the behaviour of ARGO floats](../examples/tutorial_Argofloats.ipynb).
+- [Add diffusion to approximate subgrid-scale processes and unresolved physics](../examples/tutorial_diffusion.ipynb).
+- [Convert velocities between units in m s<sup>-1</sup> and degrees s<sup>-1</sup>](../examples/tutorial_velocityconversion.ipynb).
 ```
 
 ## 4. Execute
@@ -188,10 +185,10 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime)
 
 To analyse the particle data generated in the simulation, we need to define a `parcels.ParticleFile` and add it as an argument to `parcels.ParticleSet.execute()`. The output will be written in a [parquet format](https://parquet.apache.org/), which can be opened as a `polars.DataFrame`. The dataset will contain the particle data with at least `t`, `z`, `y` and `x`, for each particle at timesteps defined by the `outputdt` argument.
 
-There are many ways to analyze particle output, and although we provide [a short tutorial to get started](./tutorial_output.ipynb), we recommend writing your own analysis code and checking out [related Lagrangian analysis projects in our community page](../community/index.md#analysis-code).
+There are many ways to analyze particle output, and although we provide [a short tutorial to get started](./tutorial_output.ipynb), we recommend writing your own analysis code and checking out [related Lagrangian analysis projects in our community page](../../community/index.md#analysis-code).
 
 ```{admonition} 🖥️ Learn how to run a simulation
 :class: seealso
-- [Choose an appropriate timestep and integrator](../user_guide/examples/tutorial_dt_integrators.ipynb)
+- [Choose an appropriate timestep and integrator](../examples/tutorial_dt_integrators.ipynb)
 - [Work with Parcels output](./tutorial_output.ipynb)
 ```

…/getting_started/explanation_concepts.md …/getting_started/explanation_concepts.mddocs/getting_started/explanation_concepts.md renamed to docs/user_guide/getting_started/explanation_concepts.md docs/getting_started/explanation_concepts.md renamed to docs/user_guide/getting_started/explanation_concepts.md

@@ -14,13 +14,19 @@ The steps below are the installation instructions for Linux, macOS and Windows.
 
 **Step 2:** Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the `base` environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, `trajan` (a trajectory plotting dependency used in the notebooks) and the nice-to-have cartopy and jupyter packages: -->
 
-Parcels v4 is in active development and hasn't been released.
+Parcels v4 is in active development.
 
-A pre-release version of Parcels (i.e., the latest version on `main`) can be installed via conda using the following instructions (which creates an environment `parcels-env`, activates it, installs Parcels from a custom pre-release channel that we're using, and installs some additional helper packages).
+A pre-release version of Parcels (i.e., the latest version on `main`) can be installed via conda using the following instructions (which creates an environment `parcelsv4-env`, activates it, installs Parcels from a custom pre-release channel that we're using, and installs some additional helper packages).
+
+```{warning}
+Before installing the latest version of Parcels, we *highly* recommend creating a new environment so that it doesn't affect your current environment (which you may be using for your research).
+
+You can find your current environment with `conda env list` and identifying the environment with a `*` next to it. At any point, you can use `conda activate ...` (replacing `...` with the name that had the `*` next to it) to return to your environment with version 3 of Parcels.
+```
 
 ```bash
-conda create -n parcels-env python
-conda activate parcels-env
+conda create -n parcelsv4-env python
+conda activate parcelsv4-env
 conda config --add channels conda-forge
 conda install -c https://prefix.dev/parcels parcels
 conda install trajan cartopy jupyter
@@ -45,4 +51,4 @@ The next time you start a terminal and want to work with Parcels, activate the e
 
 ## Installation for developers
 
-See the [development section in our contributing guide](../development/index.md#development) for development instructions.
+See the [development section in our contributing guide](../../development/index.md#development) for development instructions.