diff --git a/docs/_static/LAdiag-logo.svg b/docs/_static/LAdiag-logo.svg
new file mode 100644
index 000000000..b5641b507
--- /dev/null
+++ b/docs/_static/LAdiag-logo.svg
@@ -0,0 +1,32 @@
+
+
+
+
diff --git a/docs/_static/clam-full-white-buffer.svg b/docs/_static/clam-full-white-buffer.svg
new file mode 100644
index 000000000..ec46c8093
--- /dev/null
+++ b/docs/_static/clam-full-white-buffer.svg
@@ -0,0 +1,103 @@
+
+
diff --git a/docs/_static/github-logo.svg b/docs/_static/github-logo.svg
new file mode 100644
index 000000000..8491fa78f
--- /dev/null
+++ b/docs/_static/github-logo.svg
@@ -0,0 +1,29 @@
+
+
+
+
diff --git a/docs/community/index.md b/docs/community/index.md
index d15f3ae83..1f8622256 100644
--- a/docs/community/index.md
+++ b/docs/community/index.md
@@ -1,21 +1,107 @@
# Community
-These sections contain documentation relevant to the Parcels community.
-See the sections in the primary sidebar and below to explore.
+```{toctree}
+:caption: CLAM Community
+:maxdepth: 1
+:hidden:
+
+Website
+```
```{toctree}
-:caption: User documentation
+:caption: GitHub
:maxdepth: 1
+:hidden:
-contributing
-Versioning Policy
-Release Notes
-Parcels v4.0 Migration Guide
+Discussions
+Issues
```
```{toctree}
-:caption: Maintainer documentation
+:caption: Community examples
:maxdepth: 1
+:hidden:
+
+Repository
+```
+
+Parcels users and developers interact in a vibrant community on a few different platforms. Check out the cards below to see how you can interact with us.
+
+`````{grid} 1 2 2 2
+:gutter: 4
+:padding: 2 2 0 0
+:class-container: sd-text-center
+
+````{grid-item-card} CLAM Community on Zulip
+:img-top: https://raw.githubusercontent.com/CLAM-community/CLAM-community.github.io/ca1b93cb79410f7ffbbca7ae6860c5d5e0430d31/docs/assets/branding/svg/clam-full-white-buffer.svg
+:shadow: md
+
+If you are doing any kind of Lagrangian modelling and/or analysis check out the CLAM (Computational Lagrangian Analysis and Modelling) Community
+
+```{image} https://img.shields.io/badge/Zulip-50ADFF?style=for-the-badge&logo=Zulip&logoColor=white
+:width: 30%
+:target: https://clam-community.zulipchat.com/
+```
+
++++
+
+```{button-link} https://clam-community.github.io/
+:color: secondary
+:expand:
+
+To the CLAM website
+```
+````
+````{grid-item-card} GitHub
+:img-top: ../_static/github-logo.svg
+:shadow: md
+
+If you need more help with Parcels, try the Discussions page on **GitHub**. If you think you found a bug, please feel free to file an Issue.
+
++++
+
+```{button-link} https://github.com/Parcels-code/parcels/discussions
+:color: secondary
+:expand:
+
+Ask a question in the Discussions
+```
+```{button-link} https://github.com/Parcels-code/parcels/issues
+:color: secondary
+:expand:
+
+Report a bug with an Issue
+```
+````
+````{grid-item-card} Sharing user code
+:shadow: md
+
+Curious to see if someone has already written the custom `Kernel` you are thinking of or runs **Parcels** with the same hydrodynamic data? Check out the parcels_contributions repository and share examples with other users!
+
++++
+
+```{button-link} https://github.com/Parcels-code/parcels_contributions
+:click-parent:
+:color: secondary
+:expand:
+
+Share custom Parcels code
+```
+````
+````{grid-item-card} Lagrangian Diagnostics
+:img-top: ../_static/LAdiag-logo.svg
+:shadow: md
+
+Are you interested in advanced analysis and diagnostics of Parcels output or Lagrangian trajectories in general? The Lagrangian Diagnostics project provides code and descriptions of different analyses.
+
++++
+
+```{button-link} https://github.com/Parcels-code/Lagrangian_diags
+:click-parent:
+:color: secondary
+:expand:
-maintainer
+Visit Lagrangian Diagnostics
```
+````
+`````
diff --git a/docs/conf.py b/docs/conf.py
index a29d7ab1c..6bb23549f 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,6 +40,7 @@
"nbsphinx",
"numpydoc",
"sphinxcontrib.mermaid",
+ "sphinx_design",
]
# Add any paths that contain templates here, relative to this directory.
@@ -113,7 +114,7 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+exclude_patterns = ["_build", "**.ipynb_checkpoints", "user_guide/examples_v3"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
@@ -205,6 +206,8 @@
}
],
"announcement": "WARNING: This documentation is built for v4 of Parcels, which is unreleased and in active development. Use the version switcher in the bottom right to select your version of Parcels, or see stable docs.",
+ "header_links_before_dropdown": 8,
+ "navbar_align": "left",
}
html_context = {
@@ -520,3 +523,8 @@ def linkcode_resolve(domain, info):
# If false, no index is generated.
# epub_use_index = True
+
+# -- Options for MyST parser ----------------------------------------------
+myst_heading_anchors = 3
+
+myst_enable_extensions = ["substitution"]
diff --git a/docs/development/docsguide.md b/docs/development/docsguide.md
new file mode 100644
index 000000000..2735c7cb7
--- /dev/null
+++ b/docs/development/docsguide.md
@@ -0,0 +1,20 @@
+# Documentation Notes
+
+## Vision
+
+We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our documentation based heavily on a few common resources.
+
+```{note}
+TODO: outline functions of the documentation based on resources
+```
+
+### Resources
+
+- [Divio Documentation System](https://docs.divio.com/documentation-system/)
+- [PyOpenSci Documentation Guide](https://www.pyopensci.org/python-package-guide/documentation/index.html#)
+- [Write the Docs Guide](https://www.writethedocs.org/guide/)
+- [NumPy Documentation Article](https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community)
+
+## 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.
diff --git a/docs/community/contributing.md b/docs/development/index.md
similarity index 97%
rename from docs/community/contributing.md
rename to docs/development/index.md
index 828b148cc..1183eb743 100644
--- a/docs/community/contributing.md
+++ b/docs/development/index.md
@@ -1,5 +1,24 @@
# Contributing to Parcels
+```{toctree}
+:caption: User documentation
+:maxdepth: 1
+:hidden:
+
+Contributing Guidelines
+Versioning Policy
+Release Notes
+```
+
+```{toctree}
+:caption: Maintainer documentation
+:maxdepth: 1
+:hidden:
+
+maintainer
+docsguide
+```
+
## Why contribute?
[Lagrangian Ocean Analysis](https://doi.org/10.1016/j.ocemod.2017.11.008) is one of the primary modelling tools available to oceanographers to understand how ocean currents transport material. This modelling approach allows researchers to model the ocean and understand the [movement of water](https://doi.org/10.1029/2023GL105662) in the ocean itself (or even [on other planets](https://doi.org/10.3847/1538-4357/ac9d94)), as well as the transport of [nutrients](https://doi.org/10.1029/2023GL108001), [marine organisms](https://doi.org/10.3354/meps14526), [oil](https://doi.org/10.1590/0001-3765202220210391), [plastic](https://doi.org/10.1038/s41561-023-01216-0), as well as [almost](https://doi.org/10.1016/j.robot.2024.104730) [anything](https://doi.org/10.1111/cobi.14295) [else](https://doi.org/10.1016/j.marpolbul.2023.115254) that would be adrift at sea. Since ocean currents play a key role in climate by storing heat and carbon, and also in the formation of the 'plastic soup', understanding transport phenomena in the ocean is crucial to support a more sustainable future.
@@ -37,7 +56,7 @@ Exactly how to use Git and GitHub is beyond the scope of this documentation, and
There are many ways that you can contribute to Parcels. You can:
- Participate in discussion about Parcels, either through the [issues](https://github.com/Parcels-code/parcels/issues) or [discussions](https://github.com/Parcels-code/parcels/discussions) tab
-- Suggest improvements to [tutorials](../documentation/index.md)
+- Suggest improvements to [tutorials and how-to guides](../user_guide/index.md)
- Suggest improvements to [documentation](../index.md)
- Write code (fix bugs, implement features, codebase improvements, etc)
diff --git a/docs/community/maintainer.md b/docs/development/maintainer.md
similarity index 96%
rename from docs/community/maintainer.md
rename to docs/development/maintainer.md
index 043125691..d8d5dd4fa 100644
--- a/docs/community/maintainer.md
+++ b/docs/development/maintainer.md
@@ -27,6 +27,6 @@
- Update parcels-code.org
- Parcels development status
- Check feature tiles
- - Check for broken links on oceanparcels using [this tracking issue](https://github.com/Parcels-code/oceanparcels_website/issues/85)
+ - Check for broken links on oceanparcels using [this tracking issue](https://github.com/Parcels-code/parcels-code.org/issues/85)
- (once package is available on conda) Re-build the Binder
- Ask for the shared parcels environment on [Lorenz](https://github.com/IMAU-oceans/Lorenz) to be updated
diff --git a/docs/community/policies.md b/docs/development/policies.md
similarity index 100%
rename from docs/community/policies.md
rename to docs/development/policies.md
diff --git a/docs/documentation/index.md b/docs/documentation/index.md
deleted file mode 100644
index d57007514..000000000
--- a/docs/documentation/index.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Documentation and Tutorials
-
-Shown below are several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels.
-
-```{note}
-The tutorials written for Parcels v3 are currently being updated for Parcels v4. Shown below are only the notebooks which have been updated.
-[Feel free to post a Discussion on GitHub](https://github.com/Parcels-code/Parcels/discussions/categories/ideas) if you feel like v4 needs a specific tutorial that wasn't in v3, or [post an issue](https://github.com/Parcels-code/Parcels/issues/new?template=01_feature.md) if you feel that the notebooks below can be improved!
-```
-
-```{nbgallery}
-:caption: Overview
-:name: tutorial-overview
-
-
-
-
-```
-
-```{nbgallery}
-:caption: Setting up FieldSets
-:name: tutorial-fieldsets
-
-
-
-
-
-
-
-
-
-```
-
-```{nbgallery}
-:caption: Creating ParticleSets
-:name: tutorial-particlesets
-
-../examples/tutorial_delaystart.ipynb
-```
-
-```{nbgallery}
-:caption: Writing kernels to be executed on each particle
-:name: tutorial-kernels
-
-
-../examples/tutorial_sampling.ipynb
-../examples/tutorial_Argofloats.ipynb
-../examples/tutorial_gsw_density.ipynb
-
-
-
-
-```
-
-```{nbgallery}
-:caption: Other tutorials
-:name: tutorial-other
-
-
-
-
-
-
-
-
-```
-
-```{nbgallery}
-:caption: Worked examples
-:name: tutorial-examples
-
-
-
-```
-
-## Python Example Scripts
-
-
diff --git a/docs/getting_started/concepts_overview.md b/docs/getting_started/concepts_overview.md
new file mode 100644
index 000000000..b4cccb740
--- /dev/null
+++ b/docs/getting_started/concepts_overview.md
@@ -0,0 +1,7 @@
+# Parcels concepts
+
+A markdown document explaining the core Parcels classes
+
+```{note}
+TODO: adapt from <../user_guide/examples/explanation_parcels_concepts.ipynb>
+```
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
new file mode 100644
index 000000000..eb041f1ab
--- /dev/null
+++ b/docs/getting_started/index.md
@@ -0,0 +1,27 @@
+# Getting started
+
+Getting started with parcels is easy; here you will find:
+
+```{toctree}
+Installation guide
+Quickstart tutorial
+Parcels concepts explainer
+
+
+```
+
+```{note}
+TODO: Include one line conda installation for most common use
+```
+
+```{note}
+TODO: Write quickstart tutorial. This should focus on getting users familiar with the different steps to take to run a simulation. Implicitly we should introduce them to the important concepts, but it should not be an in depth explanation. Instead we should reference to the concept overview and the reference API
+```
+
+```{note}
+TODO: Rewrite parcels concepts overview. This .md file should contain most of what is currently in the tutorial_parcels_structure notebook.
+```
+
+```{note}
+TODO: Move new output tutorial here
+```
diff --git a/docs/installation.md b/docs/getting_started/installation.md
similarity index 72%
rename from docs/installation.md
rename to docs/getting_started/installation.md
index 6cd0cb436..6c25c57b4 100644
--- a/docs/installation.md
+++ b/docs/getting_started/installation.md
@@ -1,4 +1,6 @@
-# Basic installation
+# Installation guide
+
+## Basic Installation
The simplest way to install the Parcels code is to use Anaconda and the [Parcels conda-forge package](https://anaconda.org/conda-forge/parcels) with the latest release of Parcels. This package will automatically install all the requirements for a fully functional installation of Parcels. This is the "batteries-included" solution probably suitable for most users. Note that we support Python 3.10 and higher.
@@ -27,24 +29,12 @@ For some of the examples, `pytest` also needs to be installed. This can be quick
conda activate parcels
```
-**Step 4:** Download [a zipped copy](https://docs.parcels-code.org/en/latest/_downloads/307c382eb1813dc691e8a80d6c0098f7/parcels_tutorials.zip) of the Parcels tutorials and examples and unzip it.
-
-**Step 5:** Go to the unzipped folder and run one of the examples to validate that you have a working Parcels setup:
-
-```bash
-python example_peninsula.py --fieldset 100 100
-```
-
-_Optionally:_ if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks:
-
-```bash
-jupyter notebook
-```
-
```{note}
The next time you start a terminal and want to work with Parcels, activate the environment with `conda activate parcels`.
```
-# Installation for developers
+**Step 4:** Create a Jupyter Notebook or Python script to set up your first Parcels simulation! The [quickstart tutorial](tutorial_quickstart.md) is a great way to get started immediately. You can also first read about the core [Parcels concepts](concepts_overview.md) to familiarize yourself with the classes and methods you will use.
+
+## Installation for developers
-See the [development section in our contributing guide](./community/contributing.md#development) for development instructions.
+See the [development section in our contributing guide](../development/index.md#development) for development instructions.
diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md
new file mode 100644
index 000000000..878d4d25c
--- /dev/null
+++ b/docs/getting_started/tutorial_quickstart.md
@@ -0,0 +1,3 @@
+# Quickstart tutorial"
+
+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
diff --git a/docs/index.md b/docs/index.md
index 6c4d47d75..8bff99346 100755
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,19 +8,95 @@ 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/).
-Here you'll find [installation instructions](installation.md), [tutorials and documentation](documentation/index.md), and the [API reference](reference.md) for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
+**Version**: {{env.config.version}}
-If you need more help with Parcels, try the [Discussions page on GitHub](https://github.com/Parcels-code/parcels/discussions). If you think you found a bug, file an [Issue on GitHub](https://github.com/Parcels-code/parcels/issues). If you want to help improve Parcels, see the [Contributing](community/contributing.md) page.
+```{note}
+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.md)
+
+`````{grid} 1 2 2 2
+:gutter: 4
+:padding: 2 2 0 0
+:class-container: sd-text-center
+
+````{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.
+
++++
+
+```{button-ref} getting_started/index
+:ref-type: doc
+:click-parent:
+:color: secondary
+:expand:
+
+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:
+
++++
+
+```{button-ref} user_guide/index
+:ref-type: doc
+:click-parent:
+:color: secondary
+:expand:
+
+To the user guide
+```
+````
+````{grid-item-card} Development
+:shadow: md
+
+We encourage anyone to help improve **Parcels**: read our guidelines to get started!
+
++++
+
+```{button-ref} development/index
+:ref-type: doc
+:click-parent:
+:color: secondary
+:expand:
+
+Contributing guidelines
+```
+````
+````{grid-item-card} Community
+:shadow: md
+
+Want to interact with other users and **Parcels** developers?
+
++++
+
+```{button-ref} community/index
+:ref-type: doc
+:click-parent:
+:color: secondary
+:expand:
+
+Connect with our community!
+```
+````
+`````
```{toctree}
:maxdepth: 2
:hidden:
Home
-v4
-Installation
-Tutorials & Documentation
+Getting started
+User guide
+Community
+Development
API reference
-Contributing, Release Notes and more
+v4
Parcels website
```
diff --git a/docs/documentation/additional_examples.md b/docs/user_guide/additional_examples.md
similarity index 86%
rename from docs/documentation/additional_examples.md
rename to docs/user_guide/additional_examples.md
index f60e247bd..6224dd2fd 100644
--- a/docs/documentation/additional_examples.md
+++ b/docs/user_guide/additional_examples.md
@@ -1,6 +1,10 @@
# Python Example Scripts
-## example_brownian.py
+```{note}
+The examples written for Parcels v3 are currently being updated for Parcels v4. Shown below are only the examples which have been updated.
+```
+
+
diff --git a/docs/examples/images/NEMO_ghost_vel.png b/docs/user_guide/examples/images/NEMO_ghost_vel.png
similarity index 100%
rename from docs/examples/images/NEMO_ghost_vel.png
rename to docs/user_guide/examples/images/NEMO_ghost_vel.png
diff --git a/docs/examples/images/NEMO_latBC.png b/docs/user_guide/examples/images/NEMO_latBC.png
similarity index 100%
rename from docs/examples/images/NEMO_latBC.png
rename to docs/user_guide/examples/images/NEMO_latBC.png
diff --git a/docs/examples/images/ParcelsParallel.png b/docs/user_guide/examples/images/ParcelsParallel.png
similarity index 100%
rename from docs/examples/images/ParcelsParallel.png
rename to docs/user_guide/examples/images/ParcelsParallel.png
diff --git a/docs/examples/images/grid_comparison.png b/docs/user_guide/examples/images/grid_comparison.png
similarity index 100%
rename from docs/examples/images/grid_comparison.png
rename to docs/user_guide/examples/images/grid_comparison.png
diff --git a/docs/examples/images/homepage.gif b/docs/user_guide/examples/images/homepage.gif
similarity index 100%
rename from docs/examples/images/homepage.gif
rename to docs/user_guide/examples/images/homepage.gif
diff --git a/docs/examples/images/parcels_user_diagram.png b/docs/user_guide/examples/images/parcels_user_diagram.png
similarity index 100%
rename from docs/examples/images/parcels_user_diagram.png
rename to docs/user_guide/examples/images/parcels_user_diagram.png
diff --git a/docs/examples/images/parcels_user_diagram.svg b/docs/user_guide/examples/images/parcels_user_diagram.svg
similarity index 100%
rename from docs/examples/images/parcels_user_diagram.svg
rename to docs/user_guide/examples/images/parcels_user_diagram.svg
diff --git a/docs/examples/images/tutorial_geospatial_google_earth.png b/docs/user_guide/examples/images/tutorial_geospatial_google_earth.png
similarity index 100%
rename from docs/examples/images/tutorial_geospatial_google_earth.png
rename to docs/user_guide/examples/images/tutorial_geospatial_google_earth.png
diff --git a/docs/examples/images/tutorial_geospatial_kepler.png b/docs/user_guide/examples/images/tutorial_geospatial_kepler.png
similarity index 100%
rename from docs/examples/images/tutorial_geospatial_kepler.png
rename to docs/user_guide/examples/images/tutorial_geospatial_kepler.png
diff --git a/docs/examples/images/tutorial_geospatial_qgis.png b/docs/user_guide/examples/images/tutorial_geospatial_qgis.png
similarity index 100%
rename from docs/examples/images/tutorial_geospatial_qgis.png
rename to docs/user_guide/examples/images/tutorial_geospatial_qgis.png
diff --git a/docs/examples/tutorial_Argofloats.ipynb b/docs/user_guide/examples/tutorial_Argofloats.ipynb
similarity index 100%
rename from docs/examples/tutorial_Argofloats.ipynb
rename to docs/user_guide/examples/tutorial_Argofloats.ipynb
diff --git a/docs/examples/tutorial_delaystart.ipynb b/docs/user_guide/examples/tutorial_delaystart.ipynb
similarity index 100%
rename from docs/examples/tutorial_delaystart.ipynb
rename to docs/user_guide/examples/tutorial_delaystart.ipynb
diff --git a/docs/examples/tutorial_gsw_density.ipynb b/docs/user_guide/examples/tutorial_gsw_density.ipynb
similarity index 100%
rename from docs/examples/tutorial_gsw_density.ipynb
rename to docs/user_guide/examples/tutorial_gsw_density.ipynb
diff --git a/docs/examples/tutorial_output.ipynb b/docs/user_guide/examples/tutorial_output.ipynb
similarity index 98%
rename from docs/examples/tutorial_output.ipynb
rename to docs/user_guide/examples/tutorial_output.ipynb
index 13778feca..faf5908e5 100644
--- a/docs/examples/tutorial_output.ipynb
+++ b/docs/user_guide/examples/tutorial_output.ipynb
@@ -21,7 +21,7 @@
"- [**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](https://lagrangian-diags.readthedocs.io/en/latest/index.html) project. The [TrajAn package]() can be used to read and plot datasets of Lagrangian trajectories."
+ "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."
]
},
{
diff --git a/docs/examples/tutorial_sampling.ipynb b/docs/user_guide/examples/tutorial_sampling.ipynb
similarity index 100%
rename from docs/examples/tutorial_sampling.ipynb
rename to docs/user_guide/examples/tutorial_sampling.ipynb
diff --git a/docs/examples_v3/documentation_LargeRunsOutput.ipynb b/docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_LargeRunsOutput.ipynb
rename to docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb
diff --git a/docs/examples_v3/documentation_MPI.ipynb b/docs/user_guide/examples_v3/documentation_MPI.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_MPI.ipynb
rename to docs/user_guide/examples_v3/documentation_MPI.ipynb
diff --git a/docs/examples_v3/documentation_advanced_zarr.ipynb b/docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_advanced_zarr.ipynb
rename to docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb
diff --git a/docs/examples_v3/documentation_geospatial.ipynb b/docs/user_guide/examples_v3/documentation_geospatial.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_geospatial.ipynb
rename to docs/user_guide/examples_v3/documentation_geospatial.ipynb
diff --git a/docs/examples_v3/documentation_homepage_animation.ipynb b/docs/user_guide/examples_v3/documentation_homepage_animation.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_homepage_animation.ipynb
rename to docs/user_guide/examples_v3/documentation_homepage_animation.ipynb
diff --git a/docs/examples_v3/documentation_indexing.ipynb b/docs/user_guide/examples_v3/documentation_indexing.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_indexing.ipynb
rename to docs/user_guide/examples_v3/documentation_indexing.ipynb
diff --git a/docs/examples_v3/documentation_stuck_particles.ipynb b/docs/user_guide/examples_v3/documentation_stuck_particles.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_stuck_particles.ipynb
rename to docs/user_guide/examples_v3/documentation_stuck_particles.ipynb
diff --git a/docs/examples_v3/documentation_unstuck_Agrid.ipynb b/docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb
similarity index 100%
rename from docs/examples_v3/documentation_unstuck_Agrid.ipynb
rename to docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb
diff --git a/docs/examples_v3/example_brownian.py b/docs/user_guide/examples_v3/example_brownian.py
similarity index 100%
rename from docs/examples_v3/example_brownian.py
rename to docs/user_guide/examples_v3/example_brownian.py
diff --git a/docs/examples_v3/example_decaying_moving_eddy.py b/docs/user_guide/examples_v3/example_decaying_moving_eddy.py
similarity index 100%
rename from docs/examples_v3/example_decaying_moving_eddy.py
rename to docs/user_guide/examples_v3/example_decaying_moving_eddy.py
diff --git a/docs/examples_v3/example_globcurrent.py b/docs/user_guide/examples_v3/example_globcurrent.py
similarity index 100%
rename from docs/examples_v3/example_globcurrent.py
rename to docs/user_guide/examples_v3/example_globcurrent.py
diff --git a/docs/examples_v3/example_mitgcm.py b/docs/user_guide/examples_v3/example_mitgcm.py
similarity index 100%
rename from docs/examples_v3/example_mitgcm.py
rename to docs/user_guide/examples_v3/example_mitgcm.py
diff --git a/docs/examples_v3/example_moving_eddies.py b/docs/user_guide/examples_v3/example_moving_eddies.py
similarity index 100%
rename from docs/examples_v3/example_moving_eddies.py
rename to docs/user_guide/examples_v3/example_moving_eddies.py
diff --git a/docs/examples_v3/example_nemo_curvilinear.py b/docs/user_guide/examples_v3/example_nemo_curvilinear.py
similarity index 100%
rename from docs/examples_v3/example_nemo_curvilinear.py
rename to docs/user_guide/examples_v3/example_nemo_curvilinear.py
diff --git a/docs/examples_v3/example_ofam.py b/docs/user_guide/examples_v3/example_ofam.py
similarity index 100%
rename from docs/examples_v3/example_ofam.py
rename to docs/user_guide/examples_v3/example_ofam.py
diff --git a/docs/examples_v3/example_peninsula.py b/docs/user_guide/examples_v3/example_peninsula.py
similarity index 100%
rename from docs/examples_v3/example_peninsula.py
rename to docs/user_guide/examples_v3/example_peninsula.py
diff --git a/docs/examples_v3/example_radial_rotation.py b/docs/user_guide/examples_v3/example_radial_rotation.py
similarity index 100%
rename from docs/examples_v3/example_radial_rotation.py
rename to docs/user_guide/examples_v3/example_radial_rotation.py
diff --git a/docs/examples_v3/example_stommel.py b/docs/user_guide/examples_v3/example_stommel.py
similarity index 100%
rename from docs/examples_v3/example_stommel.py
rename to docs/user_guide/examples_v3/example_stommel.py
diff --git a/docs/examples_v3/parcels_tutorial.ipynb b/docs/user_guide/examples_v3/parcels_tutorial.ipynb
similarity index 100%
rename from docs/examples_v3/parcels_tutorial.ipynb
rename to docs/user_guide/examples_v3/parcels_tutorial.ipynb
diff --git a/docs/examples_v3/tutorial_analyticaladvection.ipynb b/docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_analyticaladvection.ipynb
rename to docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb
diff --git a/docs/examples_v3/tutorial_croco_3D.ipynb b/docs/user_guide/examples_v3/tutorial_croco_3D.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_croco_3D.ipynb
rename to docs/user_guide/examples_v3/tutorial_croco_3D.ipynb
diff --git a/docs/examples_v3/tutorial_diffusion.ipynb b/docs/user_guide/examples_v3/tutorial_diffusion.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_diffusion.ipynb
rename to docs/user_guide/examples_v3/tutorial_diffusion.ipynb
diff --git a/docs/examples_v3/tutorial_interaction.ipynb b/docs/user_guide/examples_v3/tutorial_interaction.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_interaction.ipynb
rename to docs/user_guide/examples_v3/tutorial_interaction.ipynb
diff --git a/docs/examples_v3/tutorial_interpolation.ipynb b/docs/user_guide/examples_v3/tutorial_interpolation.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_interpolation.ipynb
rename to docs/user_guide/examples_v3/tutorial_interpolation.ipynb
diff --git a/docs/examples_v3/tutorial_kernelloop.ipynb b/docs/user_guide/examples_v3/tutorial_kernelloop.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_kernelloop.ipynb
rename to docs/user_guide/examples_v3/tutorial_kernelloop.ipynb
diff --git a/docs/examples_v3/tutorial_nemo_3D.ipynb b/docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_nemo_3D.ipynb
rename to docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb
diff --git a/docs/examples_v3/tutorial_nemo_curvilinear.ipynb b/docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_nemo_curvilinear.ipynb
rename to docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb
diff --git a/docs/examples_v3/tutorial_parcels_structure.ipynb b/docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_parcels_structure.ipynb
rename to docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb
diff --git a/docs/examples_v3/tutorial_particle_field_interaction.ipynb b/docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_particle_field_interaction.ipynb
rename to docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb
diff --git a/docs/examples_v3/tutorial_peninsula_AvsCgrid.ipynb b/docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_peninsula_AvsCgrid.ipynb
rename to docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb
diff --git a/docs/examples_v3/tutorial_periodic_boundaries.ipynb b/docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_periodic_boundaries.ipynb
rename to docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb
diff --git a/docs/examples_v3/tutorial_splitparticles.ipynb b/docs/user_guide/examples_v3/tutorial_splitparticles.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_splitparticles.ipynb
rename to docs/user_guide/examples_v3/tutorial_splitparticles.ipynb
diff --git a/docs/examples_v3/tutorial_stommel_uxarray.ipynb b/docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_stommel_uxarray.ipynb
rename to docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb
diff --git a/docs/examples_v3/tutorial_timevaryingdepthdimensions.ipynb b/docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_timevaryingdepthdimensions.ipynb
rename to docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb
diff --git a/docs/examples_v3/tutorial_unitconverters.ipynb b/docs/user_guide/examples_v3/tutorial_unitconverters.ipynb
similarity index 100%
rename from docs/examples_v3/tutorial_unitconverters.ipynb
rename to docs/user_guide/examples_v3/tutorial_unitconverters.ipynb
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
new file mode 100644
index 000000000..3c271dece
--- /dev/null
+++ b/docs/user_guide/index.md
@@ -0,0 +1,86 @@
+# User guide
+
+The core of our user guide is a series of Jupyter notebooks which document how to implement specific Lagrangian simulations with the flexibility of **Parcels**. Before diving into these advanced _how-to_ guides, we suggest users get started by reading the explanation of the core concepts and trying the quickstart tutorial. For a description of the specific classes and functions, check out the [API reference](../reference.md). To discover other community resources, check out our [Community](../community/index.md) page.
+
+```{note}
+The tutorials written for Parcels v3 are currently being updated for Parcels v4. Shown below are only the notebooks which have been updated.
+[Feel free to post a Discussion on GitHub](https://github.com/Parcels-code/Parcels/discussions/categories/ideas) if you feel like v4 needs a specific tutorial that wasn't in v3, or [post an issue](https://github.com/Parcels-code/Parcels/issues/new?template=01_feature.md) if you feel that the notebooks below can be improved!
+```
+
+## Getting started
+
+```{nbgallery}
+:caption: Getting started
+:name: tutorial-overview
+
+
+
+examples/tutorial_output.ipynb
+```
+
+## How to:
+
+```{note}
+**Migrate from v3 to v4** using [this migration guide](v4-migration.md)
+```
+
+```{nbgallery}
+:caption: Set up FieldSets
+:name: tutorial-fieldsets
+
+
+
+
+
+
+
+
+
+```
+
+```{nbgallery}
+:caption: Create ParticleSets
+:name: tutorial-particlesets
+
+examples/tutorial_delaystart.ipynb
+```
+
+```{nbgallery}
+:caption: Write a custom kernel
+:name: tutorial-kernels
+
+
+examples/tutorial_sampling.ipynb
+examples/tutorial_gsw_density.ipynb
+
+
+
+
+```
+
+```{nbgallery}
+:caption: Other tutorials
+:name: tutorial-other
+
+
+
+
+
+
+
+
+```
+
+```{nbgallery}
+:caption: Worked examples
+:name: tutorial-examples
+
+examples/tutorial_Argofloats.ipynb
+
+```
+
+```{toctree}
+:hidden:
+v3 to v4 migration guide
+Example scripts
+```
diff --git a/docs/community/v4-migration.md b/docs/user_guide/v4-migration.md
similarity index 100%
rename from docs/community/v4-migration.md
rename to docs/user_guide/v4-migration.md
diff --git a/docs/v4/index.md b/docs/v4/index.md
index 16ffa40f8..73c29c370 100644
--- a/docs/v4/index.md
+++ b/docs/v4/index.md
@@ -22,5 +22,5 @@ api
nojit
TODO
Parcels v4 Project Board
-Parcels v4 migration guide <../community/v4-migration>
+Parcels v4 migration guide <../user_guide/v4-migration>
```
diff --git a/docs/v4/installation.md b/docs/v4/installation.md
index 8928ffd5d..aaa60ea10 100644
--- a/docs/v4/installation.md
+++ b/docs/v4/installation.md
@@ -1,6 +1,6 @@
# Install an alpha version of Parcels v4
-During development of Parcels v4, we are uploading versions of the package to an [index on prefix.dev](https://prefix.dev/channels/parcels/packages/parcels). This allows users to easily install an unreleased version without having to do a [development install](../installation.md)! Give it a spin!
+During development of Parcels v4, we are uploading versions of the package to an [index on prefix.dev](https://prefix.dev/channels/parcels/packages/parcels). This allows users to easily install an unreleased version without having to do a [development install](../development/index.md#development)! Give it a spin!
```{warning}
Before installing an alpha version of Parcels, we *highly* recommend creating a new environment so that doesn't affect package versions in your current environment (which you may be using for your research).
diff --git a/pixi.toml b/pixi.toml
index 5ce112b53..1673dbf5a 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -72,7 +72,7 @@ pytest-cov = "*"
[feature.test.tasks]
tests = "pytest"
-tests-notebooks = "pytest --nbval-lax docs/examples"
+tests-notebooks = "pytest --nbval-lax docs/user_guide/examples"
[feature.notebooks.dependencies]
@@ -91,6 +91,7 @@ pydata-sphinx-theme = "*"
sphinx-autobuild = "*"
myst-parser = "*"
sphinxcontrib-mermaid = "*"
+sphinx-design = "*"
[feature.docs.tasks]
docs = "sphinx-build docs docs/_build"