[DOCS] Changing user guide to a nested structure

README.md

@@ -11,7 +11,7 @@
 [![asv](https://img.shields.io/badge/benchmarked%20by-asv-blue.svg?style=flat)](https://github.com/Parcels-code/parcels-benchmarks)
 [![codecov](https://codecov.io/gh/Parcels-code/parcels/branch/main/graph/badge.svg)](https://codecov.io/gh/Parcels-code/parcels)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5353/badge)](https://bestpractices.coreinfrastructure.org/projects/5353)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Parcels-code/parcels/main?labpath=docs%2Fuser_guide%2Fexamples%2Ftutorial_Argofloats.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Parcels-code/parcels/main?labpath=docs%2Fuser_guide%2Fconvert_Argofloats.ipynb)
 [![LinkedIn](https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff)](https://www.linkedin.com/company/parcelscode/)
 
 > This branch contains version 4 of Parcels. Change to `v3-support` to see v3 (which is currently in maintainence mode) or the tags to browse stable versions of Parcels.
@@ -20,7 +20,7 @@
 
 ![CopernicusParticles](https://github.com/Parcels-code/Parcels/blob/main/docs/_static/homepage.gif?raw=true)
 
-_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the [Copernicus Marine Service](https://marine.copernicus.eu). See [here](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_homepage_animation.html) for the script to create this animation yourself._
+_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the [Copernicus Marine Service](https://marine.copernicus.eu). See [here](https://docs.parcels-code.org/en/latest/user_guide/misc_homepage_animation.html) for the script to create this animation yourself._
 
 ### Parcels manuscript and code
 
@@ -38,7 +38,7 @@ _Kehl, C, PD Nooteboom, MLA Kaandorp and E van Sebille (2023) Efficiently simula
 
 ### Further information
 
-See [parcels-code.org](http://parcels-code.org/) for further information about [installing](https://docs.parcels-code.org/en/latest/user_guide/getting_started/installation.html) and [running](https://docs.parcels-code.org/en/latest/user_guide/index.html) the Parcels code, as well as extended [API reference](https://docs.parcels-code.org/en/latest/reference/parcels/index.html) of the methods and classes.
+See [parcels-code.org](http://parcels-code.org/) for further information about [installing](https://docs.parcels-code.org/en/latest/user_guide/installation.html) and [running](https://docs.parcels-code.org/en/latest/user_guide/index.html) the Parcels code, as well as extended [API reference](https://docs.parcels-code.org/en/latest/reference/parcels/index.html) of the methods and classes.
 
 ### Contributors
 

docs/conf.py

@@ -89,7 +89,45 @@
 
 # Redirects for moved/deleted pages, handled by sphinxext-rediraffe. Paths are relative to
 # the docs folder, e.g. "user_guide/examples/tutorial_old.ipynb": "user_guide/examples/tutorial_new.ipynb"
-rediraffe_redirects = {}
+rediraffe_redirects = {
+    # Flattening user_guide/examples and user_guide/getting_started into user_guide (GH-3038)
+    "user_guide/examples/explanation_copernicusmarine.md": "user_guide/convert_copernicusmarine.md",
+    "user_guide/examples/explanation_grids.ipynb": "user_guide/fieldsets_grids.ipynb",
+    "user_guide/examples/explanation_interpolation.md": "user_guide/interpolation_explanation.md",
+    "user_guide/examples/explanation_kernelloop.md": "user_guide/kernels_loopexplanation.md",
+    "user_guide/examples/explanation_performance.md": "user_guide/simulation_performance.md",
+    "user_guide/examples/explanation_writing_convert_functions.md": "user_guide/convert_writing_functions.md",
+    "user_guide/examples/tutorial_Argofloats.ipynb": "user_guide/example_Argofloats.ipynb",
+    "user_guide/examples/tutorial_aifs.ipynb": "user_guide/convert_aifs.ipynb",
+    "user_guide/examples/tutorial_croco_3D.ipynb": "user_guide/convert_croco_3D.ipynb",
+    "user_guide/examples/tutorial_delaystart.ipynb": "user_guide/particlesets_delaystart.ipynb",
+    "user_guide/examples/tutorial_delft3d.ipynb": "user_guide/convert_delft3d.ipynb",
+    "user_guide/examples/tutorial_diffusion.ipynb": "user_guide/example_diffusion.ipynb",
+    "user_guide/examples/tutorial_dt_integrators.ipynb": "user_guide/simulation_dt_integrators.ipynb",
+    "user_guide/examples/tutorial_fesom.ipynb": "user_guide/convert_fesom.ipynb",
+    "user_guide/examples/tutorial_gsw_density.ipynb": "user_guide/example_gsw_density.ipynb",
+    "user_guide/examples/tutorial_homepage_animation.md": "user_guide/misc_homepage_animation.md",
+    "user_guide/examples/tutorial_interaction.ipynb": "user_guide/example_interaction.ipynb",
+    "user_guide/examples/tutorial_interpolation.ipynb": "user_guide/interpolation_tutorial.ipynb",
+    "user_guide/examples/tutorial_manipulating_field_data.ipynb": "user_guide/fieldsets_manipulating_field_data.ipynb",
+    "user_guide/examples/tutorial_mitgcm.ipynb": "user_guide/convert_mitgcm.ipynb",
+    "user_guide/examples/tutorial_mom6.ipynb": "user_guide/convert_mom6.ipynb",
+    "user_guide/examples/tutorial_nemo.ipynb": "user_guide/convert_nemo.ipynb",
+    "user_guide/examples/tutorial_nestedgrids.ipynb": "user_guide/fieldsets_nestedgrids.ipynb",
+    "user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb": "user_guide/interpolation_peninsula_AvsCgrid.ipynb",
+    "user_guide/examples/tutorial_sampling.ipynb": "user_guide/kernels_sampling.ipynb",
+    "user_guide/examples/tutorial_schism.ipynb": "user_guide/convert_schism.ipynb",
+    "user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/fieldsets_sigma_coordinates.ipynb",
+    "user_guide/examples/tutorial_statuscodes.md": "user_guide/kernels_statuscodes.ipynb",
+    "user_guide/examples/tutorial_stuck_particles.ipynb": "user_guide/interpolation_stuck_particles.ipynb",
+    "user_guide/examples/tutorial_unstuck_Agrid.ipynb": "user_guide/interpolation_unstuck_Agrid.ipynb",
+    "user_guide/examples/tutorial_velocityconversion.ipynb": "user_guide/fieldsets_velocityconversion.ipynb",
+    "user_guide/examples/tutorial_write_in_kernel.ipynb": "user_guide/kernels_write_in_kernel.ipynb",
+    "user_guide/getting_started/explanation_concepts.md": "user_guide/gettingstarted_concepts.md",
+    "user_guide/getting_started/installation.md": "user_guide/installation.md",
+    "user_guide/getting_started/tutorial_output.ipynb": "user_guide/gettingstarted_output.ipynb",
+    "user_guide/getting_started/tutorial_quickstart.md": "user_guide/gettingstarted_quickstart.md",
+}
 
 # Tell Jinja2 templates the build is running on Read the Docs
 if os.environ.get("READTHEDOCS", "") == "True":
@@ -213,6 +251,9 @@
     "announcement": "Parcels v4 has been released! 🎉 See <a href='https://parcels-code.org/blog/parcels-v4'>our release blog post</a> for more info",
     "header_links_before_dropdown": 8,
     "navbar_align": "left",
+    "show_nav_level": 0,
+    "collapse_navigation": True,
+    "navigation_depth": 2,
 }
 
 html_context = {

docs/index.md

@@ -6,13 +6,13 @@ Welcome to the documentation of Parcels. **Parcels** provides a set of Python cl
 :class: dark-light
 ```
 
-_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the [Copernicus Marine Service](https://marine.copernicus.eu). See [here](./user_guide/examples/tutorial_homepage_animation.md) for the script to create this animation yourself._
+_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the [Copernicus Marine Service](https://marine.copernicus.eu). See [here](./user_guide/misc_homepage_animation.md) for the script to create this animation yourself._
 
 ```{note}
 You are viewing the documentation for Parcels {{ version }}. You can browse the documentation for older versions by using the version switcher in the bottom right.
 ```
 
-**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)
+**Useful links**: [Installation instructions](user_guide/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)
 
 `````{grid} 1 2 2 2
 :gutter: 4
@@ -22,7 +22,7 @@ You are viewing the documentation for Parcels {{ version }}. You can browse the
 ````{grid-item-card} Getting started
 :shadow: md
 
-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.
+New to Parcels? Check out the [installation instructions](user_guide/installation), run the [quickstart tutorial](user_guide/gettingstarted_quickstart), and learn the [key concepts](user_guide/gettingstarted_concepts) to understand the package.
 
 +++
 

docs/user_guide/examples/tutorial_aifs.ipynb → docs/user_guide/convert_aifs.ipynb

@@ -165,7 +165,7 @@
     "\n",
     "With the dataset prepared, we can build the {py:obj}`parcels.FieldSet` using {py:func}`parcels.FieldSet.from_sgrid_conventions()`. We pass `mesh=\"spherical\"` because the velocities are given in local (spherical) coordinates. For the interpolation of the 2D and 3D fields we choose linear interpolation, which is the method most commonly used in atmospheric Lagrangian transport models.\n",
     "\n",
-    "We also speed up the I/O by using the `ChunkCachedArray` backend - see the [squeezing performance out of Parcels](./explanation_performance.md) tutorial for more details.\n"
+    "We also speed up the I/O by using the `ChunkCachedArray` backend - see the [squeezing performance out of Parcels](./simulation_performance.md) tutorial for more details.\n"
    ]
   },
   {

docs/user_guide/examples/explanation_copernicusmarine.md → docs/user_guide/convert_copernicusmarine.md

@@ -73,13 +73,13 @@ ds_fields = parcels.convert.copernicusmarine_to_sgrid(
 fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fields)
 ```
 
-Now, you will have to set the interpolation method for the UV fields to `XFreeslip`, which is more suitable for A-Grid data like the one provided by Copernicus Marine Service. This ensures that particles don't get stuck near the boundaries. See the [preventing stuck particles tutorial](./tutorial_unstuck_Agrid.ipynb) for more information.
+Now, you will have to set the interpolation method for the UV fields to `XFreeslip`, which is more suitable for A-Grid data like the one provided by Copernicus Marine Service. This ensures that particles don't get stuck near the boundaries. See the [preventing stuck particles tutorial](./interpolation_unstuck_Agrid.ipynb) for more information.
 
 ```
 fieldset.UV.interp_method = parcels.interpolators.XFreeslip()
 ```
 
-For [better performance](./explanation_performance.md), we should also use the `ChunkCachedArray` backend
+For [better performance](./simulation_performance.md), we should also use the `ChunkCachedArray` backend
 
 ```
 fieldset.to_chunk_cached_arrays()

docs/user_guide/examples/tutorial_delft3d.ipynb → docs/user_guide/convert_delft3d.ipynb

@@ -241,7 +241,7 @@
     "pset = parcels.ParticleSet(fieldset, x=X, y=Y)\n",
     "\n",
     "outfile = parcels.ParticleFile(\n",
-    "    \"tutorial_delft3d_particles.parquet\", outputdt=np.timedelta64(15, \"m\"), mode=\"w\"\n",
+    "    \"delft3d_particles.parquet\", outputdt=np.timedelta64(15, \"m\"), mode=\"w\"\n",
     ")\n",
     "\n",
     "pset.execute(\n",
@@ -268,7 +268,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = parcels.read_particlefile(\"tutorial_delft3d_particles.parquet\")\n",
+    "df = parcels.read_particlefile(\"delft3d_particles.parquet\")\n",
     "fig, ax = plt.subplots(figsize=(8, 6))\n",
     "ax.triplot(triang, color=\"k\", lw=0.3, alpha=0.5, label=\"Flow mesh\", zorder=2)\n",
     "ax.set_aspect(\"equal\")\n",

docs/user_guide/examples/tutorial_fesom.ipynb → docs/user_guide/convert_fesom.ipynb

@@ -18,7 +18,7 @@
     "3. Build a {py:obj}`parcels.FieldSet` with {py:func}`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](./gettingstarted_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), {py:func}`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](./gettingstarted_quickstart.md), {py:func}`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:"
    ]
@@ -285,7 +285,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The particles drift through the channel following the FESOM2 velocity field. From here, the rest of Parcels — custom kernels, sampling fields onto particles, writing your own interpolators — works identically to structured grids. See the [interpolation tutorial](./tutorial_interpolation.ipynb) for the available `Ux*` interpolators and how to write a custom one."
+    "The particles drift through the channel following the FESOM2 velocity field. From here, the rest of Parcels — custom kernels, sampling fields onto particles, writing your own interpolators — works identically to structured grids. See the [interpolation tutorial](./interpolation_tutorial.ipynb) for the available `Ux*` interpolators and how to write a custom one."
    ]
   }
  ],

docs/user_guide/examples/tutorial_mitgcm.ipynb → docs/user_guide/convert_mitgcm.ipynb

@@ -13,7 +13,7 @@
    "id": "1",
    "metadata": {},
    "source": [
-    "This tutorial will show how to run a 3D simulation with output from the MITgcm model. The key thing about MITgcm is that its output is on a C-grid, which means that the U and V velocity components are not defined at the same location as the particle positions. Parcels has built-in functionality to deal with C-grid data. See also the [Nemo tutorial](tutorial_nemo.ipynb) for another example of C-grid data."
+    "This tutorial will show how to run a 3D simulation with output from the MITgcm model. The key thing about MITgcm is that its output is on a C-grid, which means that the U and V velocity components are not defined at the same location as the particle positions. Parcels has built-in functionality to deal with C-grid data. See also the [Nemo tutorial](convert_nemo.ipynb) for another example of C-grid data."
    ]
   },
   {

docs/user_guide/examples/tutorial_mom6.ipynb → docs/user_guide/convert_mom6.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# 🖥️ MOM6 tutorial\n",
     "\n",
-    "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_nemo.html) and [MITgcm tutorial](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_mitgcm.html) for other examples of C-grid data.\n",
+    "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](./convert_nemo.ipynb) and [MITgcm tutorial](./convert_mitgcm.ipynb) for other examples of C-grid data.\n",
     "\n",
     "```{note}\n",
     "The MOM6-to-SGRID converter currently only works with 2-dimensional (surface) velocity fields. If you have a dataset with 3-dimensional velocity fields, please raise an Issue on the [Parcels GitHub repository](https://github.com/Parcels-code/parcels/issues), specifying the details of your dataset and then we can provide guidance on how to handle it.\n",