From 9533fdde43e15edfc53bc96364f8c43580bb56ba Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 27 Oct 2025 15:34:35 +0100 Subject: [PATCH 01/26] implement new documentation structure as per #2310 --- docs/community/index.md | 20 +----------------- docs/conf.py | 2 +- .../contributing.md => contributing/index.md} | 19 +++++++++++++++++ .../{community => contributing}/maintainer.md | 0 docs/{community => contributing}/policies.md | 0 docs/documentation/additional_examples.md | 8 +++++-- docs/documentation/index.md | 21 +++++++++++++------ .../v4-migration.md | 0 docs/getting_started/index.md | 11 ++++++++++ docs/{ => getting_started}/installation.md | 0 docs/index.md | 11 +++++----- 11 files changed, 59 insertions(+), 33 deletions(-) rename docs/{community/contributing.md => contributing/index.md} (97%) rename docs/{community => contributing}/maintainer.md (100%) rename docs/{community => contributing}/policies.md (100%) rename docs/{community => documentation}/v4-migration.md (100%) create mode 100644 docs/getting_started/index.md rename docs/{ => getting_started}/installation.md (100%) diff --git a/docs/community/index.md b/docs/community/index.md index d15f3ae83..4346c67ce 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,21 +1,3 @@ # Community -These sections contain documentation relevant to the Parcels community. -See the sections in the primary sidebar and below to explore. - -```{toctree} -:caption: User documentation -:maxdepth: 1 - -contributing -Versioning Policy -Release Notes -Parcels v4.0 Migration Guide -``` - -```{toctree} -:caption: Maintainer documentation -:maxdepth: 1 - -maintainer -``` +Parcels users and developers interact in a vibrant community: if you are running any kind of Lagrangian simulations check out [Zulip](). 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](contributing/index.md) page. diff --git a/docs/conf.py b/docs/conf.py index a29d7ab1c..4b48bf672 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -113,7 +113,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", "examples_v3"] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/community/contributing.md b/docs/contributing/index.md similarity index 97% rename from docs/community/contributing.md rename to docs/contributing/index.md index 828b148cc..fa21baac4 100644 --- a/docs/community/contributing.md +++ b/docs/contributing/index.md @@ -1,5 +1,24 @@ # Contributing to Parcels +```{toctree} +:caption: User documentation +:maxdepth: 1 +:hidden: + +Contributing Guidelines +Versioning Policy +Release Notes +Parcels v4.0 Migration Guide <../documentation/v4-migration> +``` + +```{toctree} +:caption: Maintainer documentation +:maxdepth: 1 +:hidden: + +maintainer +``` + ## 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. diff --git a/docs/community/maintainer.md b/docs/contributing/maintainer.md similarity index 100% rename from docs/community/maintainer.md rename to docs/contributing/maintainer.md diff --git a/docs/community/policies.md b/docs/contributing/policies.md similarity index 100% rename from docs/community/policies.md rename to docs/contributing/policies.md diff --git a/docs/documentation/additional_examples.md b/docs/documentation/additional_examples.md index f60e247bd..6224dd2fd 100644 --- a/docs/documentation/additional_examples.md +++ b/docs/documentation/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/documentation/index.md b/docs/documentation/index.md index b9f99adf9..fcc65f8b6 100644 --- a/docs/documentation/index.md +++ b/docs/documentation/index.md @@ -7,8 +7,10 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. [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: Overview +:caption: Getting started :name: tutorial-overview @@ -16,8 +18,14 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ``` +## How to: + +```{note} +**Migrate from v3 to v4** using [this migration guide](v4-migration.md) +``` + ```{nbgallery} -:caption: Setting up FieldSets +:caption: Set up FieldSets :name: tutorial-fieldsets @@ -31,18 +39,19 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ``` ```{nbgallery} -:caption: Creating ParticleSets +:caption: Create ParticleSets :name: tutorial-particlesets ``` ```{nbgallery} -:caption: Writing kernels to be executed on each particle +:caption: Write a custom kernel :name: tutorial-kernels ../examples/tutorial_sampling.ipynb +../examples/tutorial_gsw_density.ipynb @@ -70,8 +79,8 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ``` -## Python Example Scripts + diff --git a/docs/community/v4-migration.md b/docs/documentation/v4-migration.md similarity index 100% rename from docs/community/v4-migration.md rename to docs/documentation/v4-migration.md diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md new file mode 100644 index 000000000..319781625 --- /dev/null +++ b/docs/getting_started/index.md @@ -0,0 +1,11 @@ +# Getting started + +Getting started with parcels is easy; here you will find: + +```{toctree} +The installation guide + + +``` diff --git a/docs/installation.md b/docs/getting_started/installation.md similarity index 100% rename from docs/installation.md rename to docs/getting_started/installation.md diff --git a/docs/index.md b/docs/index.md index 6c4d47d75..1bd29795d 100755 --- a/docs/index.md +++ b/docs/index.md @@ -8,9 +8,9 @@ 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. +Here you'll find [installation instructions](getting_started/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. -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. +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](contributing/index.md) page. ```{toctree} :maxdepth: 2 @@ -18,9 +18,10 @@ If you need more help with Parcels, try the [Discussions page on GitHub](https:/ Home v4 -Installation -Tutorials & Documentation +Getting started +Documentation +Community +Contributing API reference -Contributing, Release Notes and more Parcels website ``` From f7d1027dae65037d0c77a7ce4ff2e5e979d7ce99 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 27 Oct 2025 16:05:17 +0100 Subject: [PATCH 02/26] fix some links --- docs/community/index.md | 2 +- docs/conf.py | 3 +++ docs/contributing/index.md | 2 +- docs/contributing/maintainer.md | 2 +- docs/getting_started/installation.md | 2 +- docs/v4/index.md | 2 +- docs/v4/installation.md | 2 +- 7 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/community/index.md b/docs/community/index.md index 4346c67ce..2eb1a1d85 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,3 +1,3 @@ # Community -Parcels users and developers interact in a vibrant community: if you are running any kind of Lagrangian simulations check out [Zulip](). 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](contributing/index.md) page. +Parcels users and developers interact in a vibrant community: if you are doing any kind of Lagrangian modelling and/or analysis check out the [CLAM community on Zulip](https://clam-community.github.io/). 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](../contributing/index.md) page. diff --git a/docs/conf.py b/docs/conf.py index 4b48bf672..a6abeb6a5 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -520,3 +520,6 @@ def linkcode_resolve(domain, info): # If false, no index is generated. # epub_use_index = True + +# -- Options for MyST parser ---------------------------------------------- +myst_heading_anchors = 3 diff --git a/docs/contributing/index.md b/docs/contributing/index.md index fa21baac4..44aa53cb8 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -5,7 +5,7 @@ :maxdepth: 1 :hidden: -Contributing Guidelines +Contributing Guidelines Versioning Policy Release Notes Parcels v4.0 Migration Guide <../documentation/v4-migration> diff --git a/docs/contributing/maintainer.md b/docs/contributing/maintainer.md index 043125691..d8d5dd4fa 100644 --- a/docs/contributing/maintainer.md +++ b/docs/contributing/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/getting_started/installation.md b/docs/getting_started/installation.md index 6cd0cb436..8384ad419 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -47,4 +47,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](./community/contributing.md#development) for development instructions. +See the [development section in our contributing guide](../contributing/index.md#development) for development instructions. diff --git a/docs/v4/index.md b/docs/v4/index.md index 16ffa40f8..8b1c6755e 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 <../documentation/v4-migration> ``` diff --git a/docs/v4/installation.md b/docs/v4/installation.md index 8928ffd5d..a9b31277e 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](../contributing/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). From d56f00faf495d3a62099f477dafaa0376c3de809 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 28 Oct 2025 10:26:40 +0100 Subject: [PATCH 03/26] restructure homepage --- docs/conf.py | 3 ++ docs/index.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++-- pixi.toml | 1 + 3 files changed, 81 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a6abeb6a5..347f6dbe4 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. @@ -523,3 +524,5 @@ def linkcode_resolve(domain, info): # -- Options for MyST parser ---------------------------------------------- myst_heading_anchors = 3 + +myst_enable_extensions = ["substitution"] diff --git a/docs/index.md b/docs/index.md index 1bd29795d..e378f6a2a 100755 --- a/docs/index.md +++ b/docs/index.md @@ -8,9 +8,84 @@ 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](getting_started/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](contributing/index.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} documentation/index +:ref-type: doc +:click-parent: +:color: secondary +:expand: + +To the documentation +``` +```` +````{grid-item-card} Contributing +:shadow: md + +We encourage anyone to help improve **Parcels**: read our guidelines to get started! + ++++ + +```{button-ref} contributing/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 diff --git a/pixi.toml b/pixi.toml index 5ce112b53..bc34f87ff 100644 --- a/pixi.toml +++ b/pixi.toml @@ -91,6 +91,7 @@ pydata-sphinx-theme = "*" sphinx-autobuild = "*" myst-parser = "*" sphinxcontrib-mermaid = "*" +sphinx-design = "*" [feature.docs.tasks] docs = "sphinx-build docs docs/_build" From 766d409862735b0f86f7e012d1d88f7f0bb94bd7 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 28 Oct 2025 11:41:30 +0100 Subject: [PATCH 04/26] update community page --- docs/_static/clam-full-white-buffer.svg | 103 ++++++++++++++++++++++++ docs/_static/github-logo.svg | 29 +++++++ docs/community/index.md | 84 ++++++++++++++++++- 3 files changed, 215 insertions(+), 1 deletion(-) create mode 100644 docs/_static/clam-full-white-buffer.svg create mode 100644 docs/_static/github-logo.svg 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 2eb1a1d85..a7379db09 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,3 +1,85 @@ # Community -Parcels users and developers interact in a vibrant community: if you are doing any kind of Lagrangian modelling and/or analysis check out the [CLAM community on Zulip](https://clam-community.github.io/). 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](../contributing/index.md) page. +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: ../_static/clam-full-white-buffer.svg +:shadow: md + +If you are doing any kind of Lagrangian modelling and/or analysis check out CLAM (Computational Lagrangian Analysis and Modelling) on Zulip and their online community meetings + ++++ + +```{button-link} https://clam-community.github.io/ +:click-parent: +: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 +``` +````` + +```{toctree} +:caption: CLAM Community +:maxdepth: 1 +:hidden: + +Website +``` +```{toctree} +:caption: GitHub +:maxdepth: 1 +:hidden: + +Discussions +Issues +``` + +```{toctree} +:caption: parcels_contributions +:maxdepth: 1 +:hidden: + +Repository +``` From fa2549725636820cbc7c92bea0c5dd1365140c09 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 28 Oct 2025 12:00:53 +0100 Subject: [PATCH 05/26] fix some toctrees --- docs/community/index.md | 49 +++++++++++++++++++------------------ docs/contributing/index.md | 1 - docs/documentation/index.md | 12 ++++----- 3 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/community/index.md b/docs/community/index.md index a7379db09..d30c961cb 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1,5 +1,30 @@ # Community +```{toctree} +:caption: CLAM Community +:maxdepth: 1 +:hidden: + +Website +``` + +```{toctree} +:caption: GitHub +:maxdepth: 1 +:hidden: + +Discussions +Issues +``` + +```{toctree} +:caption: parcels_contributions +: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 @@ -59,27 +84,3 @@ Curious to see if someone has already written the custom `Kernel` you are thinki Share custom Parcels code ``` ````` - -```{toctree} -:caption: CLAM Community -:maxdepth: 1 -:hidden: - -Website -``` -```{toctree} -:caption: GitHub -:maxdepth: 1 -:hidden: - -Discussions -Issues -``` - -```{toctree} -:caption: parcels_contributions -:maxdepth: 1 -:hidden: - -Repository -``` diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 44aa53cb8..be05229c5 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -8,7 +8,6 @@ Contributing Guidelines Versioning Policy Release Notes -Parcels v4.0 Migration Guide <../documentation/v4-migration> ``` ```{toctree} diff --git a/docs/documentation/index.md b/docs/documentation/index.md index fcc65f8b6..d322f5329 100644 --- a/docs/documentation/index.md +++ b/docs/documentation/index.md @@ -1,5 +1,11 @@ # Documentation and Tutorials +```{toctree} +:hidden: +v3 to v4 migration guide +Example scripts +``` + Shown below are several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. ```{note} @@ -78,9 +84,3 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ../examples/tutorial_Argofloats.ipynb ``` - - From 08c29ab400e2838d189e37514ba633b26b17159e Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 28 Oct 2025 15:50:17 +0100 Subject: [PATCH 06/26] rename documentation to user guide, consisting of tutorial, explanation, and how-to guides --- docs/contributing/index.md | 2 +- docs/index.md | 6 +++--- docs/{documentation => user_guide}/additional_examples.md | 0 docs/{documentation => user_guide}/index.md | 5 +++-- docs/{documentation => user_guide}/v4-migration.md | 0 docs/v4/index.md | 2 +- 6 files changed, 8 insertions(+), 7 deletions(-) rename docs/{documentation => user_guide}/additional_examples.md (100%) rename docs/{documentation => user_guide}/index.md (80%) rename docs/{documentation => user_guide}/v4-migration.md (100%) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index be05229c5..51998e6cf 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -55,7 +55,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/index.md b/docs/index.md index e378f6a2a..17e6cf667 100755 --- a/docs/index.md +++ b/docs/index.md @@ -44,13 +44,13 @@ Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and e +++ -```{button-ref} documentation/index +```{button-ref} user_guide/index :ref-type: doc :click-parent: :color: secondary :expand: -To the documentation +To the user guide ``` ```` ````{grid-item-card} Contributing @@ -94,7 +94,7 @@ Connect with our community! Home v4 Getting started -Documentation +Documentation Community Contributing API reference diff --git a/docs/documentation/additional_examples.md b/docs/user_guide/additional_examples.md similarity index 100% rename from docs/documentation/additional_examples.md rename to docs/user_guide/additional_examples.md diff --git a/docs/documentation/index.md b/docs/user_guide/index.md similarity index 80% rename from docs/documentation/index.md rename to docs/user_guide/index.md index d322f5329..c30039597 100644 --- a/docs/documentation/index.md +++ b/docs/user_guide/index.md @@ -1,12 +1,13 @@ -# Documentation and Tutorials +# User guide ```{toctree} :hidden: v3 to v4 migration guide Example scripts +User contributions ``` -Shown below are several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. +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 Kernels and examples written by users, check out the [parcels contributing repository](https://github.com/Parcels-code/parcels_contributions). For a description of the specific classes and functions, check out the [API reference](../reference.md). ```{note} The tutorials written for Parcels v3 are currently being updated for Parcels v4. Shown below are only the notebooks which have been updated. diff --git a/docs/documentation/v4-migration.md b/docs/user_guide/v4-migration.md similarity index 100% rename from docs/documentation/v4-migration.md rename to docs/user_guide/v4-migration.md diff --git a/docs/v4/index.md b/docs/v4/index.md index 8b1c6755e..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 <../documentation/v4-migration> +Parcels v4 migration guide <../user_guide/v4-migration> ``` From 0c8eacd85749cca4a1b513632908e9a8d87843ec Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Wed, 29 Oct 2025 15:56:00 +0100 Subject: [PATCH 07/26] add LA Diag and Zulip logos --- docs/_static/LAdiag-logo.svg | 32 ++++++++++++++++++++++++++++++++ docs/community/index.md | 23 ++++++++++++++++++++++- 2 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/_static/LAdiag-logo.svg 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/community/index.md b/docs/community/index.md index d30c961cb..6f8c18aa0 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -36,7 +36,11 @@ Parcels users and developers interact in a vibrant community on a few different :img-top: ../_static/clam-full-white-buffer.svg :shadow: md -If you are doing any kind of Lagrangian modelling and/or analysis check out CLAM (Computational Lagrangian Analysis and Modelling) on Zulip and their online community meetings +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% +``` +++ @@ -83,4 +87,21 @@ Curious to see if someone has already written the custom `Kernel` you are thinki 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: + +Visit Lagrangian Diagnostics +``` +```` ````` From 1a315653178fff8e4cf57d721de5d5e27864fb67 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Thu, 30 Oct 2025 09:57:18 +0100 Subject: [PATCH 08/26] move examples under user_guide --- docs/conf.py | 2 +- .../examples/images/NEMO_ghost_vel.png | Bin .../examples/images/NEMO_latBC.png | Bin .../examples/images/ParcelsParallel.png | Bin .../examples/images/grid_comparison.png | Bin .../examples/images/homepage.gif | Bin .../examples/images/parcels_user_diagram.png | Bin .../examples/images/parcels_user_diagram.svg | 0 .../tutorial_geospatial_google_earth.png | Bin .../images/tutorial_geospatial_kepler.png | Bin .../images/tutorial_geospatial_qgis.png | Bin .../examples/tutorial_Argofloats.ipynb | 0 .../examples/tutorial_gsw_density.ipynb | 0 .../examples/tutorial_sampling.ipynb | 0 .../documentation_LargeRunsOutput.ipynb | 0 .../examples_v3/documentation_MPI.ipynb | 0 .../documentation_advanced_zarr.ipynb | 0 .../documentation_geospatial.ipynb | 0 .../documentation_homepage_animation.ipynb | 0 .../examples_v3/documentation_indexing.ipynb | 0 .../documentation_stuck_particles.ipynb | 0 .../documentation_unstuck_Agrid.ipynb | 0 .../examples_v3/example_brownian.py | 0 .../example_decaying_moving_eddy.py | 0 .../examples_v3/example_globcurrent.py | 0 .../examples_v3/example_mitgcm.py | 0 .../examples_v3/example_moving_eddies.py | 0 .../examples_v3/example_nemo_curvilinear.py | 0 .../examples_v3/example_ofam.py | 0 .../examples_v3/example_peninsula.py | 0 .../examples_v3/example_radial_rotation.py | 0 .../examples_v3/example_stommel.py | 0 .../examples_v3/parcels_tutorial.ipynb | 0 .../tutorial_analyticaladvection.ipynb | 0 .../examples_v3/tutorial_croco_3D.ipynb | 0 .../examples_v3/tutorial_delaystart.ipynb | 0 .../examples_v3/tutorial_diffusion.ipynb | 0 .../examples_v3/tutorial_interaction.ipynb | 0 .../examples_v3/tutorial_interpolation.ipynb | 0 .../examples_v3/tutorial_kernelloop.ipynb | 0 .../examples_v3/tutorial_nemo_3D.ipynb | 0 .../tutorial_nemo_curvilinear.ipynb | 0 .../examples_v3/tutorial_output.ipynb | 0 .../tutorial_parcels_structure.ipynb | 0 .../tutorial_particle_field_interaction.ipynb | 0 .../tutorial_peninsula_AvsCgrid.ipynb | 0 .../tutorial_periodic_boundaries.ipynb | 0 .../tutorial_stommel_uxarray.ipynb | 0 .../tutorial_timevaryingdepthdimensions.ipynb | 0 .../examples_v3/tutorial_unitconverters.ipynb | 0 docs/user_guide/index.md | 56 +++++++++--------- 51 files changed, 29 insertions(+), 29 deletions(-) rename docs/{ => user_guide}/examples/images/NEMO_ghost_vel.png (100%) rename docs/{ => user_guide}/examples/images/NEMO_latBC.png (100%) rename docs/{ => user_guide}/examples/images/ParcelsParallel.png (100%) rename docs/{ => user_guide}/examples/images/grid_comparison.png (100%) rename docs/{ => user_guide}/examples/images/homepage.gif (100%) rename docs/{ => user_guide}/examples/images/parcels_user_diagram.png (100%) rename docs/{ => user_guide}/examples/images/parcels_user_diagram.svg (100%) rename docs/{ => user_guide}/examples/images/tutorial_geospatial_google_earth.png (100%) rename docs/{ => user_guide}/examples/images/tutorial_geospatial_kepler.png (100%) rename docs/{ => user_guide}/examples/images/tutorial_geospatial_qgis.png (100%) rename docs/{ => user_guide}/examples/tutorial_Argofloats.ipynb (100%) rename docs/{ => user_guide}/examples/tutorial_gsw_density.ipynb (100%) rename docs/{ => user_guide}/examples/tutorial_sampling.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_LargeRunsOutput.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_MPI.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_advanced_zarr.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_geospatial.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_homepage_animation.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_indexing.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_stuck_particles.ipynb (100%) rename docs/{ => user_guide}/examples_v3/documentation_unstuck_Agrid.ipynb (100%) rename docs/{ => user_guide}/examples_v3/example_brownian.py (100%) rename docs/{ => user_guide}/examples_v3/example_decaying_moving_eddy.py (100%) rename docs/{ => user_guide}/examples_v3/example_globcurrent.py (100%) rename docs/{ => user_guide}/examples_v3/example_mitgcm.py (100%) rename docs/{ => user_guide}/examples_v3/example_moving_eddies.py (100%) rename docs/{ => user_guide}/examples_v3/example_nemo_curvilinear.py (100%) rename docs/{ => user_guide}/examples_v3/example_ofam.py (100%) rename docs/{ => user_guide}/examples_v3/example_peninsula.py (100%) rename docs/{ => user_guide}/examples_v3/example_radial_rotation.py (100%) rename docs/{ => user_guide}/examples_v3/example_stommel.py (100%) rename docs/{ => user_guide}/examples_v3/parcels_tutorial.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_analyticaladvection.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_croco_3D.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_delaystart.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_diffusion.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_interaction.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_interpolation.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_kernelloop.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_nemo_3D.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_nemo_curvilinear.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_output.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_parcels_structure.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_particle_field_interaction.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_peninsula_AvsCgrid.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_periodic_boundaries.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_stommel_uxarray.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_timevaryingdepthdimensions.ipynb (100%) rename docs/{ => user_guide}/examples_v3/tutorial_unitconverters.ipynb (100%) diff --git a/docs/conf.py b/docs/conf.py index 347f6dbe4..75413374f 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -114,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", "examples_v3"] +exclude_patterns = ["_build", "**.ipynb_checkpoints", "user_guide/examples_v3"] # The reST default role (used for this markup: `text`) to use for all # documents. 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_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_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_delaystart.ipynb b/docs/user_guide/examples_v3/tutorial_delaystart.ipynb similarity index 100% rename from docs/examples_v3/tutorial_delaystart.ipynb rename to docs/user_guide/examples_v3/tutorial_delaystart.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_output.ipynb b/docs/user_guide/examples_v3/tutorial_output.ipynb similarity index 100% rename from docs/examples_v3/tutorial_output.ipynb rename to docs/user_guide/examples_v3/tutorial_output.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_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 index c30039597..a10f461b9 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -4,7 +4,7 @@ :hidden: v3 to v4 migration guide Example scripts -User contributions +Community examples ``` 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 Kernels and examples written by users, check out the [parcels contributing repository](https://github.com/Parcels-code/parcels_contributions). For a description of the specific classes and functions, check out the [API reference](../reference.md). @@ -20,9 +20,9 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. :caption: Getting started :name: tutorial-overview - - - + + + ``` ## How to: @@ -35,53 +35,53 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. :caption: Set up FieldSets :name: tutorial-fieldsets - - - - - - - - + + + + + + + + ``` ```{nbgallery} :caption: Create ParticleSets :name: tutorial-particlesets - + ``` ```{nbgallery} :caption: Write a custom kernel :name: tutorial-kernels - -../examples/tutorial_sampling.ipynb -../examples/tutorial_gsw_density.ipynb - - - - + +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 +examples/tutorial_Argofloats.ipynb ``` From 71096a9ea1ed2caf911c617d7d9c9cb26435635d Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Thu, 30 Oct 2025 12:09:14 +0100 Subject: [PATCH 09/26] introduce per-file docstring rules to apply to stable v4 code --- pyproject.toml | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 564d92605..79b88a2fd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -103,14 +103,6 @@ ignore = [ "RUF046", # Value being cast to `int` is already an integer # TODO: ignore for now (requires more work). Remove ignore once fixed - # Missing docstring in public module - "D100", - # Missing docstring in public class - "D101", - # Missing docstring in public method - "D102", - # Missing docstring in public function - "D103", # Missing docstring in public package "D104", # Missing docstring in magic method @@ -126,6 +118,19 @@ ignore = [ "F811", ] +[tool.ruff.lint.per-file-ignores] +# Ignore docstring rules everywhere except for the stable files (particleset.py). +"!src/parcels/_core/{particleset}.py" = [ + # Missing docstring in public module + "D100", + # Missing docstring in public class + "D101", + # Missing docstring in public method + "D102", + # Missing docstring in public function + "D103", +] + [tool.ruff.lint.pydocstyle] convention = "numpy" From ac81305934128738c0b1aaea6c65cac5214cb1b5 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Thu, 30 Oct 2025 12:40:04 +0100 Subject: [PATCH 10/26] fix Zulip link --- docs/community/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/index.md b/docs/community/index.md index 6f8c18aa0..24ddf086d 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -40,12 +40,12 @@ If you are doing any kind of Lagrangian modelling and/or analysis check out the ```{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/ -:click-parent: :color: secondary :expand: From 902f3d5eeff494f126528658fe8295319951de8a Mon Sep 17 00:00:00 2001 From: Reint Date: Mon, 3 Nov 2025 11:22:21 +0100 Subject: [PATCH 11/26] Link to GitHub image Co-authored-by: Nick Hodgskin <36369090+VeckoTheGecko@users.noreply.github.com> --- docs/community/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/index.md b/docs/community/index.md index 24ddf086d..150ee8b69 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -33,7 +33,7 @@ Parcels users and developers interact in a vibrant community on a few different :class-container: sd-text-center ````{grid-item-card} CLAM Community on Zulip -:img-top: ../_static/clam-full-white-buffer.svg +: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 From 9bb0ea65c3b67909c44094ff9ee366a7123c9a18 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 11:20:41 +0100 Subject: [PATCH 12/26] rename "contributing" to "development" --- docs/{contributing => development}/index.md | 0 docs/{contributing => development}/maintainer.md | 0 docs/{contributing => development}/policies.md | 0 docs/getting_started/installation.md | 2 +- docs/index.md | 6 +++--- docs/v4/installation.md | 2 +- 6 files changed, 5 insertions(+), 5 deletions(-) rename docs/{contributing => development}/index.md (100%) rename docs/{contributing => development}/maintainer.md (100%) rename docs/{contributing => development}/policies.md (100%) diff --git a/docs/contributing/index.md b/docs/development/index.md similarity index 100% rename from docs/contributing/index.md rename to docs/development/index.md diff --git a/docs/contributing/maintainer.md b/docs/development/maintainer.md similarity index 100% rename from docs/contributing/maintainer.md rename to docs/development/maintainer.md diff --git a/docs/contributing/policies.md b/docs/development/policies.md similarity index 100% rename from docs/contributing/policies.md rename to docs/development/policies.md diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 8384ad419..a1ea02138 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -47,4 +47,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](../contributing/index.md#development) for development instructions. +See the [development section in our contributing guide](../development/index.md#development) for development instructions. diff --git a/docs/index.md b/docs/index.md index 17e6cf667..735fe578c 100755 --- a/docs/index.md +++ b/docs/index.md @@ -53,14 +53,14 @@ Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and e To the user guide ``` ```` -````{grid-item-card} Contributing +````{grid-item-card} Development :shadow: md We encourage anyone to help improve **Parcels**: read our guidelines to get started! +++ -```{button-ref} contributing/index +```{button-ref} development/index :ref-type: doc :click-parent: :color: secondary @@ -96,7 +96,7 @@ v4 Getting started Documentation Community -Contributing +Development API reference Parcels website ``` diff --git a/docs/v4/installation.md b/docs/v4/installation.md index a9b31277e..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](../contributing/index.md#development)! 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). From 3b48b950041c95bbeee625a4d96fd379fab901bc Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 11:43:49 +0100 Subject: [PATCH 13/26] remove parcels_contributing from sidebar --- docs/community/index.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/community/index.md b/docs/community/index.md index 150ee8b69..b6dbbb14d 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -17,14 +17,6 @@ Discussions Issues ``` -```{toctree} -:caption: parcels_contributions -: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 From 2d49457f1efbeb926c72edcecb633d04752f309a Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 12:06:03 +0100 Subject: [PATCH 14/26] start scaffolding getting_started and user_guide --- docs/getting_started/concepts_overview.md | 1 + docs/getting_started/index.md | 13 ++- ...gofloats.ipynb => how-to_Argofloats.ipynb} | 0 ...density.ipynb => how-to_gsw_density.ipynb} | 0 ...l_sampling.ipynb => how-to_sampling.ipynb} | 0 ...pynb => explanation_AvsCgrid_output.ipynb} | 0 ....ipynb => explanation_grid_indexing.ipynb} | 0 ...oop.ipynb => explanation_kernelloop.ipynb} | 0 ...ynb => explanation_parcels_concepts.ipynb} | 0 ...pynb => explanation_stuck_particles.ipynb} | 0 ...put.ipynb => how-to_LargeRunsOutput.ipynb} | 0 ...cumentation_MPI.ipynb => how-to_MPI.ipynb} | 0 ..._zarr.ipynb => how-to_advanced_zarr.ipynb} | 0 ...ipynb => how-to_analyticaladvection.ipynb} | 0 ...l_croco_3D.ipynb => how-to_croco_3D.ipynb} | 0 ...laystart.ipynb => how-to_delaystart.ipynb} | 0 ...diffusion.ipynb => how-to_diffusion.ipynb} | 0 ...ospatial.ipynb => how-to_geospatial.ipynb} | 0 ....ipynb => how-to_homepage_animation.ipynb} | 0 ...raction.ipynb => how-to_interaction.ipynb} | 0 ...ation.ipynb => how-to_interpolation.ipynb} | 0 ...ial_nemo_3D.ipynb => how-to_nemo_3D.ipynb} | 0 ...ar.ipynb => how-to_nemo_curvilinear.ipynb} | 0 ...> how-to_particle_field_interaction.ipynb} | 0 ...ipynb => how-to_periodic_boundaries.ipynb} | 0 ...ray.ipynb => how-to_stommel_uxarray.ipynb} | 0 ...> how-to_timevaryingdepthdimensions.ipynb} | 0 ...ters.ipynb => how-to_unitconverters.ipynb} | 0 ...Agrid.ipynb => how-to_unstuck_Agrid.ipynb} | 0 ...torial.ipynb => tutorial_quickstart.ipynb} | 0 docs/user_guide/index.md | 100 ++++++++++-------- 31 files changed, 69 insertions(+), 45 deletions(-) create mode 100644 docs/getting_started/concepts_overview.md rename docs/user_guide/examples/{tutorial_Argofloats.ipynb => how-to_Argofloats.ipynb} (100%) rename docs/user_guide/examples/{tutorial_gsw_density.ipynb => how-to_gsw_density.ipynb} (100%) rename docs/user_guide/examples/{tutorial_sampling.ipynb => how-to_sampling.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_peninsula_AvsCgrid.ipynb => explanation_AvsCgrid_output.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_indexing.ipynb => explanation_grid_indexing.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_kernelloop.ipynb => explanation_kernelloop.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_parcels_structure.ipynb => explanation_parcels_concepts.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_stuck_particles.ipynb => explanation_stuck_particles.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_LargeRunsOutput.ipynb => how-to_LargeRunsOutput.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_MPI.ipynb => how-to_MPI.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_advanced_zarr.ipynb => how-to_advanced_zarr.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_analyticaladvection.ipynb => how-to_analyticaladvection.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_croco_3D.ipynb => how-to_croco_3D.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_delaystart.ipynb => how-to_delaystart.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_diffusion.ipynb => how-to_diffusion.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_geospatial.ipynb => how-to_geospatial.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_homepage_animation.ipynb => how-to_homepage_animation.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_interaction.ipynb => how-to_interaction.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_interpolation.ipynb => how-to_interpolation.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_nemo_3D.ipynb => how-to_nemo_3D.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_nemo_curvilinear.ipynb => how-to_nemo_curvilinear.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_particle_field_interaction.ipynb => how-to_particle_field_interaction.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_periodic_boundaries.ipynb => how-to_periodic_boundaries.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_stommel_uxarray.ipynb => how-to_stommel_uxarray.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_timevaryingdepthdimensions.ipynb => how-to_timevaryingdepthdimensions.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_unitconverters.ipynb => how-to_unitconverters.ipynb} (100%) rename docs/user_guide/examples_v3/{documentation_unstuck_Agrid.ipynb => how-to_unstuck_Agrid.ipynb} (100%) rename docs/user_guide/examples_v3/{parcels_tutorial.ipynb => tutorial_quickstart.ipynb} (100%) diff --git a/docs/getting_started/concepts_overview.md b/docs/getting_started/concepts_overview.md new file mode 100644 index 000000000..ae64924d3 --- /dev/null +++ b/docs/getting_started/concepts_overview.md @@ -0,0 +1 @@ +A markdown document explaining the core Parcels classes \ No newline at end of file diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 319781625..0b43796ed 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -5,7 +5,18 @@ Getting started with parcels is easy; here you will find: ```{toctree} The installation guide ``` +```{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. +``` \ No newline at end of file diff --git a/docs/user_guide/examples/tutorial_Argofloats.ipynb b/docs/user_guide/examples/how-to_Argofloats.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_Argofloats.ipynb rename to docs/user_guide/examples/how-to_Argofloats.ipynb diff --git a/docs/user_guide/examples/tutorial_gsw_density.ipynb b/docs/user_guide/examples/how-to_gsw_density.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_gsw_density.ipynb rename to docs/user_guide/examples/how-to_gsw_density.ipynb diff --git a/docs/user_guide/examples/tutorial_sampling.ipynb b/docs/user_guide/examples/how-to_sampling.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_sampling.ipynb rename to docs/user_guide/examples/how-to_sampling.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb b/docs/user_guide/examples_v3/explanation_AvsCgrid_output.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb rename to docs/user_guide/examples_v3/explanation_AvsCgrid_output.ipynb diff --git a/docs/user_guide/examples_v3/documentation_indexing.ipynb b/docs/user_guide/examples_v3/explanation_grid_indexing.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_indexing.ipynb rename to docs/user_guide/examples_v3/explanation_grid_indexing.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_kernelloop.ipynb b/docs/user_guide/examples_v3/explanation_kernelloop.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_kernelloop.ipynb rename to docs/user_guide/examples_v3/explanation_kernelloop.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb b/docs/user_guide/examples_v3/explanation_parcels_concepts.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb rename to docs/user_guide/examples_v3/explanation_parcels_concepts.ipynb diff --git a/docs/user_guide/examples_v3/documentation_stuck_particles.ipynb b/docs/user_guide/examples_v3/explanation_stuck_particles.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_stuck_particles.ipynb rename to docs/user_guide/examples_v3/explanation_stuck_particles.ipynb diff --git a/docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb b/docs/user_guide/examples_v3/how-to_LargeRunsOutput.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb rename to docs/user_guide/examples_v3/how-to_LargeRunsOutput.ipynb diff --git a/docs/user_guide/examples_v3/documentation_MPI.ipynb b/docs/user_guide/examples_v3/how-to_MPI.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_MPI.ipynb rename to docs/user_guide/examples_v3/how-to_MPI.ipynb diff --git a/docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb b/docs/user_guide/examples_v3/how-to_advanced_zarr.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb rename to docs/user_guide/examples_v3/how-to_advanced_zarr.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb b/docs/user_guide/examples_v3/how-to_analyticaladvection.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb rename to docs/user_guide/examples_v3/how-to_analyticaladvection.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_croco_3D.ipynb b/docs/user_guide/examples_v3/how-to_croco_3D.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_croco_3D.ipynb rename to docs/user_guide/examples_v3/how-to_croco_3D.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_delaystart.ipynb b/docs/user_guide/examples_v3/how-to_delaystart.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_delaystart.ipynb rename to docs/user_guide/examples_v3/how-to_delaystart.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_diffusion.ipynb b/docs/user_guide/examples_v3/how-to_diffusion.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_diffusion.ipynb rename to docs/user_guide/examples_v3/how-to_diffusion.ipynb diff --git a/docs/user_guide/examples_v3/documentation_geospatial.ipynb b/docs/user_guide/examples_v3/how-to_geospatial.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_geospatial.ipynb rename to docs/user_guide/examples_v3/how-to_geospatial.ipynb diff --git a/docs/user_guide/examples_v3/documentation_homepage_animation.ipynb b/docs/user_guide/examples_v3/how-to_homepage_animation.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_homepage_animation.ipynb rename to docs/user_guide/examples_v3/how-to_homepage_animation.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_interaction.ipynb b/docs/user_guide/examples_v3/how-to_interaction.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_interaction.ipynb rename to docs/user_guide/examples_v3/how-to_interaction.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_interpolation.ipynb b/docs/user_guide/examples_v3/how-to_interpolation.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_interpolation.ipynb rename to docs/user_guide/examples_v3/how-to_interpolation.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb b/docs/user_guide/examples_v3/how-to_nemo_3D.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb rename to docs/user_guide/examples_v3/how-to_nemo_3D.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb b/docs/user_guide/examples_v3/how-to_nemo_curvilinear.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb rename to docs/user_guide/examples_v3/how-to_nemo_curvilinear.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb b/docs/user_guide/examples_v3/how-to_particle_field_interaction.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb rename to docs/user_guide/examples_v3/how-to_particle_field_interaction.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb b/docs/user_guide/examples_v3/how-to_periodic_boundaries.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb rename to docs/user_guide/examples_v3/how-to_periodic_boundaries.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb b/docs/user_guide/examples_v3/how-to_stommel_uxarray.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb rename to docs/user_guide/examples_v3/how-to_stommel_uxarray.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb b/docs/user_guide/examples_v3/how-to_timevaryingdepthdimensions.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb rename to docs/user_guide/examples_v3/how-to_timevaryingdepthdimensions.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_unitconverters.ipynb b/docs/user_guide/examples_v3/how-to_unitconverters.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_unitconverters.ipynb rename to docs/user_guide/examples_v3/how-to_unitconverters.ipynb diff --git a/docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb b/docs/user_guide/examples_v3/how-to_unstuck_Agrid.ipynb similarity index 100% rename from docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb rename to docs/user_guide/examples_v3/how-to_unstuck_Agrid.ipynb diff --git a/docs/user_guide/examples_v3/parcels_tutorial.ipynb b/docs/user_guide/examples_v3/tutorial_quickstart.ipynb similarity index 100% rename from docs/user_guide/examples_v3/parcels_tutorial.ipynb rename to docs/user_guide/examples_v3/tutorial_quickstart.ipynb diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index a10f461b9..43c7721c1 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -1,12 +1,5 @@ # User guide -```{toctree} -:hidden: -v3 to v4 migration guide -Example scripts -Community examples -``` - 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 Kernels and examples written by users, check out the [parcels contributing repository](https://github.com/Parcels-code/parcels_contributions). For a description of the specific classes and functions, check out the [API reference](../reference.md). ```{note} @@ -18,10 +11,10 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ```{nbgallery} :caption: Getting started -:name: tutorial-overview +:name: getting-started - - + + ``` @@ -33,55 +26,74 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ```{nbgallery} :caption: Set up FieldSets -:name: tutorial-fieldsets - - - - - - - - - +:name: how-to-fieldsets + + + + + + + + + + ``` ```{nbgallery} :caption: Create ParticleSets -:name: tutorial-particlesets +:name: how-to-particlesets - + ``` ```{nbgallery} -:caption: Write a custom kernel -:name: tutorial-kernels - - -examples/tutorial_sampling.ipynb -examples/tutorial_gsw_density.ipynb - - - - +:caption: Write a custom `Kernel` +:name: how-to-kernels + + + + +examples/how-to_sampling.ipynb +examples/how-to_gsw_density.ipynb + + + +``` + +```{nbgallery} +:caption: Write an `Interpolator` +:name: how-to-interpolators +``` + +```{nbgallery} +:caption: Run an accurate and efficient simulation +:name: how-to-simulation ``` ```{nbgallery} :caption: Other tutorials -:name: tutorial-other - - - - - - - - +:name: how-to-other + + + + + + + + ``` ```{nbgallery} :caption: Worked examples -:name: tutorial-examples +:name: how-to-examples -examples/tutorial_Argofloats.ipynb - +examples/how-to_Argofloats.ipynb + ``` + +```{toctree} +:hidden: +v3 to v4 migration guide +Example scripts +Community examples +``` \ No newline at end of file From 355cde089307642ebf977c022bb2ce299b81b191 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 15:18:08 +0100 Subject: [PATCH 15/26] add some more scaffolding --- docs/user_guide/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 43c7721c1..a779321a8 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -33,6 +33,7 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. + @@ -68,16 +69,18 @@ examples/how-to_gsw_density.ipynb ```{nbgallery} :caption: Run an accurate and efficient simulation :name: how-to-simulation + + + + + ``` ```{nbgallery} :caption: Other tutorials :name: how-to-other - - - From e305182bfbfd5d443109f867144282b4ceb136dd Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 16:48:09 +0100 Subject: [PATCH 16/26] remove some superfluous text and links --- docs/community/index.md | 8 ++++++++ docs/getting_started/index.md | 1 + docs/getting_started/installation.md | 14 -------------- docs/user_guide/index.md | 1 - 4 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/community/index.md b/docs/community/index.md index b6dbbb14d..1f8622256 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -17,6 +17,14 @@ Discussions Issues ``` +```{toctree} +: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 diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 0b43796ed..264c9a908 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -9,6 +9,7 @@ The installation guide - a simple tutorial on how to analyse the output from your first simulation <../examples_v3/tutorial_output.ipynb> --> ``` + ```{note} TODO: Include one line conda installation for most common use ``` diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index a1ea02138..303b72cab 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -27,20 +27,6 @@ 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`. ``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index a779321a8..fbc65b527 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -98,5 +98,4 @@ examples/how-to_Argofloats.ipynb :hidden: v3 to v4 migration guide Example scripts -Community examples ``` \ No newline at end of file From 93f9aca815ad60ae26ffd2760065ed0f2a629aa2 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Mon, 3 Nov 2025 16:51:31 +0100 Subject: [PATCH 17/26] restore ruff lint ignore --- pyproject.toml | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 79b88a2fd..564d92605 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -103,6 +103,14 @@ ignore = [ "RUF046", # Value being cast to `int` is already an integer # TODO: ignore for now (requires more work). Remove ignore once fixed + # Missing docstring in public module + "D100", + # Missing docstring in public class + "D101", + # Missing docstring in public method + "D102", + # Missing docstring in public function + "D103", # Missing docstring in public package "D104", # Missing docstring in magic method @@ -118,19 +126,6 @@ ignore = [ "F811", ] -[tool.ruff.lint.per-file-ignores] -# Ignore docstring rules everywhere except for the stable files (particleset.py). -"!src/parcels/_core/{particleset}.py" = [ - # Missing docstring in public module - "D100", - # Missing docstring in public class - "D101", - # Missing docstring in public method - "D102", - # Missing docstring in public function - "D103", -] - [tool.ruff.lint.pydocstyle] convention = "numpy" From b4bd7ff070517f4f2e41ca1fbdee9b398a9d959c Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 4 Nov 2025 11:26:57 +0100 Subject: [PATCH 18/26] change nav bar to make community, development, and API reference pages more visible --- docs/conf.py | 2 ++ docs/getting_started/concepts_overview.md | 5 ++++- docs/index.md | 4 ++-- docs/user_guide/index.md | 2 +- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 75413374f..6bb23549f 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -206,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 = { diff --git a/docs/getting_started/concepts_overview.md b/docs/getting_started/concepts_overview.md index ae64924d3..5cbef5f08 100644 --- a/docs/getting_started/concepts_overview.md +++ b/docs/getting_started/concepts_overview.md @@ -1 +1,4 @@ -A markdown document explaining the core Parcels classes \ No newline at end of file +A markdown document explaining the core Parcels classes +```{note} +TODO: adapt from <../user_guide/examples/explanation_parcels_concepts.ipynb> +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 735fe578c..8bff99346 100755 --- a/docs/index.md +++ b/docs/index.md @@ -92,11 +92,11 @@ Connect with our community! :hidden: Home -v4 Getting started -Documentation +User guide Community Development API reference +v4 Parcels website ``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index fbc65b527..62f292990 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -1,6 +1,6 @@ # 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 Kernels and examples written by users, check out the [parcels contributing repository](https://github.com/Parcels-code/parcels_contributions). For a description of the specific classes and functions, check out the [API reference](../reference.md). +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. From fe9defc214e13f359263e19a85848a7318e3c8fb Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 4 Nov 2025 11:40:44 +0100 Subject: [PATCH 19/26] Revert "start scaffolding getting_started and user_guide" to retain tutorial/documentation naming split This reverts commit 2d49457f1efbeb926c72edcecb633d04752f309a. --- docs/getting_started/index.md | 4 +- ...floats.ipynb => tutorial_Argofloats.ipynb} | 0 ...nsity.ipynb => tutorial_gsw_density.ipynb} | 0 ...sampling.ipynb => tutorial_sampling.ipynb} | 0 ...nb => documentation_LargeRunsOutput.ipynb} | 0 ...w-to_MPI.ipynb => documentation_MPI.ipynb} | 0 ...pynb => documentation_advanced_zarr.ipynb} | 0 ...l.ipynb => documentation_geospatial.ipynb} | 0 ...=> documentation_homepage_animation.ipynb} | 0 ...ing.ipynb => documentation_indexing.ipynb} | 0 ...nb => documentation_stuck_particles.ipynb} | 0 ...pynb => documentation_unstuck_Agrid.ipynb} | 0 ...uickstart.ipynb => parcels_tutorial.ipynb} | 0 ...ynb => tutorial_analyticaladvection.ipynb} | 0 ...croco_3D.ipynb => tutorial_croco_3D.ipynb} | 0 ...ystart.ipynb => tutorial_delaystart.ipynb} | 0 ...ffusion.ipynb => tutorial_diffusion.ipynb} | 0 ...ction.ipynb => tutorial_interaction.ipynb} | 0 ...ion.ipynb => tutorial_interpolation.ipynb} | 0 ...elloop.ipynb => tutorial_kernelloop.ipynb} | 0 ...o_nemo_3D.ipynb => tutorial_nemo_3D.ipynb} | 0 ....ipynb => tutorial_nemo_curvilinear.ipynb} | 0 ...ipynb => tutorial_parcels_structure.ipynb} | 0 ...tutorial_particle_field_interaction.ipynb} | 0 ...pynb => tutorial_peninsula_AvsCgrid.ipynb} | 0 ...ynb => tutorial_periodic_boundaries.ipynb} | 0 ...y.ipynb => tutorial_stommel_uxarray.ipynb} | 0 ...tutorial_timevaryingdepthdimensions.ipynb} | 0 ...rs.ipynb => tutorial_unitconverters.ipynb} | 0 docs/user_guide/index.md | 91 ++++++++----------- 30 files changed, 40 insertions(+), 55 deletions(-) rename docs/user_guide/examples/{how-to_Argofloats.ipynb => tutorial_Argofloats.ipynb} (100%) rename docs/user_guide/examples/{how-to_gsw_density.ipynb => tutorial_gsw_density.ipynb} (100%) rename docs/user_guide/examples/{how-to_sampling.ipynb => tutorial_sampling.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_LargeRunsOutput.ipynb => documentation_LargeRunsOutput.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_MPI.ipynb => documentation_MPI.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_advanced_zarr.ipynb => documentation_advanced_zarr.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_geospatial.ipynb => documentation_geospatial.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_homepage_animation.ipynb => documentation_homepage_animation.ipynb} (100%) rename docs/user_guide/examples_v3/{explanation_grid_indexing.ipynb => documentation_indexing.ipynb} (100%) rename docs/user_guide/examples_v3/{explanation_stuck_particles.ipynb => documentation_stuck_particles.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_unstuck_Agrid.ipynb => documentation_unstuck_Agrid.ipynb} (100%) rename docs/user_guide/examples_v3/{tutorial_quickstart.ipynb => parcels_tutorial.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_analyticaladvection.ipynb => tutorial_analyticaladvection.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_croco_3D.ipynb => tutorial_croco_3D.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_delaystart.ipynb => tutorial_delaystart.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_diffusion.ipynb => tutorial_diffusion.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_interaction.ipynb => tutorial_interaction.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_interpolation.ipynb => tutorial_interpolation.ipynb} (100%) rename docs/user_guide/examples_v3/{explanation_kernelloop.ipynb => tutorial_kernelloop.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_nemo_3D.ipynb => tutorial_nemo_3D.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_nemo_curvilinear.ipynb => tutorial_nemo_curvilinear.ipynb} (100%) rename docs/user_guide/examples_v3/{explanation_parcels_concepts.ipynb => tutorial_parcels_structure.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_particle_field_interaction.ipynb => tutorial_particle_field_interaction.ipynb} (100%) rename docs/user_guide/examples_v3/{explanation_AvsCgrid_output.ipynb => tutorial_peninsula_AvsCgrid.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_periodic_boundaries.ipynb => tutorial_periodic_boundaries.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_stommel_uxarray.ipynb => tutorial_stommel_uxarray.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_timevaryingdepthdimensions.ipynb => tutorial_timevaryingdepthdimensions.ipynb} (100%) rename docs/user_guide/examples_v3/{how-to_unitconverters.ipynb => tutorial_unitconverters.ipynb} (100%) diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 264c9a908..ee741dd15 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -5,7 +5,7 @@ Getting started with parcels is easy; here you will find: ```{toctree} The installation guide ``` @@ -20,4 +20,4 @@ TODO: Write quickstart tutorial. This should focus on getting users familiar wit ```{note} TODO: Rewrite parcels concepts overview. This .md file should contain most of what is currently in the tutorial_parcels_structure notebook. -``` \ No newline at end of file +``` diff --git a/docs/user_guide/examples/how-to_Argofloats.ipynb b/docs/user_guide/examples/tutorial_Argofloats.ipynb similarity index 100% rename from docs/user_guide/examples/how-to_Argofloats.ipynb rename to docs/user_guide/examples/tutorial_Argofloats.ipynb diff --git a/docs/user_guide/examples/how-to_gsw_density.ipynb b/docs/user_guide/examples/tutorial_gsw_density.ipynb similarity index 100% rename from docs/user_guide/examples/how-to_gsw_density.ipynb rename to docs/user_guide/examples/tutorial_gsw_density.ipynb diff --git a/docs/user_guide/examples/how-to_sampling.ipynb b/docs/user_guide/examples/tutorial_sampling.ipynb similarity index 100% rename from docs/user_guide/examples/how-to_sampling.ipynb rename to docs/user_guide/examples/tutorial_sampling.ipynb diff --git a/docs/user_guide/examples_v3/how-to_LargeRunsOutput.ipynb b/docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_LargeRunsOutput.ipynb rename to docs/user_guide/examples_v3/documentation_LargeRunsOutput.ipynb diff --git a/docs/user_guide/examples_v3/how-to_MPI.ipynb b/docs/user_guide/examples_v3/documentation_MPI.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_MPI.ipynb rename to docs/user_guide/examples_v3/documentation_MPI.ipynb diff --git a/docs/user_guide/examples_v3/how-to_advanced_zarr.ipynb b/docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_advanced_zarr.ipynb rename to docs/user_guide/examples_v3/documentation_advanced_zarr.ipynb diff --git a/docs/user_guide/examples_v3/how-to_geospatial.ipynb b/docs/user_guide/examples_v3/documentation_geospatial.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_geospatial.ipynb rename to docs/user_guide/examples_v3/documentation_geospatial.ipynb diff --git a/docs/user_guide/examples_v3/how-to_homepage_animation.ipynb b/docs/user_guide/examples_v3/documentation_homepage_animation.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_homepage_animation.ipynb rename to docs/user_guide/examples_v3/documentation_homepage_animation.ipynb diff --git a/docs/user_guide/examples_v3/explanation_grid_indexing.ipynb b/docs/user_guide/examples_v3/documentation_indexing.ipynb similarity index 100% rename from docs/user_guide/examples_v3/explanation_grid_indexing.ipynb rename to docs/user_guide/examples_v3/documentation_indexing.ipynb diff --git a/docs/user_guide/examples_v3/explanation_stuck_particles.ipynb b/docs/user_guide/examples_v3/documentation_stuck_particles.ipynb similarity index 100% rename from docs/user_guide/examples_v3/explanation_stuck_particles.ipynb rename to docs/user_guide/examples_v3/documentation_stuck_particles.ipynb diff --git a/docs/user_guide/examples_v3/how-to_unstuck_Agrid.ipynb b/docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_unstuck_Agrid.ipynb rename to docs/user_guide/examples_v3/documentation_unstuck_Agrid.ipynb diff --git a/docs/user_guide/examples_v3/tutorial_quickstart.ipynb b/docs/user_guide/examples_v3/parcels_tutorial.ipynb similarity index 100% rename from docs/user_guide/examples_v3/tutorial_quickstart.ipynb rename to docs/user_guide/examples_v3/parcels_tutorial.ipynb diff --git a/docs/user_guide/examples_v3/how-to_analyticaladvection.ipynb b/docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_analyticaladvection.ipynb rename to docs/user_guide/examples_v3/tutorial_analyticaladvection.ipynb diff --git a/docs/user_guide/examples_v3/how-to_croco_3D.ipynb b/docs/user_guide/examples_v3/tutorial_croco_3D.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_croco_3D.ipynb rename to docs/user_guide/examples_v3/tutorial_croco_3D.ipynb diff --git a/docs/user_guide/examples_v3/how-to_delaystart.ipynb b/docs/user_guide/examples_v3/tutorial_delaystart.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_delaystart.ipynb rename to docs/user_guide/examples_v3/tutorial_delaystart.ipynb diff --git a/docs/user_guide/examples_v3/how-to_diffusion.ipynb b/docs/user_guide/examples_v3/tutorial_diffusion.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_diffusion.ipynb rename to docs/user_guide/examples_v3/tutorial_diffusion.ipynb diff --git a/docs/user_guide/examples_v3/how-to_interaction.ipynb b/docs/user_guide/examples_v3/tutorial_interaction.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_interaction.ipynb rename to docs/user_guide/examples_v3/tutorial_interaction.ipynb diff --git a/docs/user_guide/examples_v3/how-to_interpolation.ipynb b/docs/user_guide/examples_v3/tutorial_interpolation.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_interpolation.ipynb rename to docs/user_guide/examples_v3/tutorial_interpolation.ipynb diff --git a/docs/user_guide/examples_v3/explanation_kernelloop.ipynb b/docs/user_guide/examples_v3/tutorial_kernelloop.ipynb similarity index 100% rename from docs/user_guide/examples_v3/explanation_kernelloop.ipynb rename to docs/user_guide/examples_v3/tutorial_kernelloop.ipynb diff --git a/docs/user_guide/examples_v3/how-to_nemo_3D.ipynb b/docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_nemo_3D.ipynb rename to docs/user_guide/examples_v3/tutorial_nemo_3D.ipynb diff --git a/docs/user_guide/examples_v3/how-to_nemo_curvilinear.ipynb b/docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_nemo_curvilinear.ipynb rename to docs/user_guide/examples_v3/tutorial_nemo_curvilinear.ipynb diff --git a/docs/user_guide/examples_v3/explanation_parcels_concepts.ipynb b/docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb similarity index 100% rename from docs/user_guide/examples_v3/explanation_parcels_concepts.ipynb rename to docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb diff --git a/docs/user_guide/examples_v3/how-to_particle_field_interaction.ipynb b/docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_particle_field_interaction.ipynb rename to docs/user_guide/examples_v3/tutorial_particle_field_interaction.ipynb diff --git a/docs/user_guide/examples_v3/explanation_AvsCgrid_output.ipynb b/docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb similarity index 100% rename from docs/user_guide/examples_v3/explanation_AvsCgrid_output.ipynb rename to docs/user_guide/examples_v3/tutorial_peninsula_AvsCgrid.ipynb diff --git a/docs/user_guide/examples_v3/how-to_periodic_boundaries.ipynb b/docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_periodic_boundaries.ipynb rename to docs/user_guide/examples_v3/tutorial_periodic_boundaries.ipynb diff --git a/docs/user_guide/examples_v3/how-to_stommel_uxarray.ipynb b/docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_stommel_uxarray.ipynb rename to docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb diff --git a/docs/user_guide/examples_v3/how-to_timevaryingdepthdimensions.ipynb b/docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_timevaryingdepthdimensions.ipynb rename to docs/user_guide/examples_v3/tutorial_timevaryingdepthdimensions.ipynb diff --git a/docs/user_guide/examples_v3/how-to_unitconverters.ipynb b/docs/user_guide/examples_v3/tutorial_unitconverters.ipynb similarity index 100% rename from docs/user_guide/examples_v3/how-to_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 index 62f292990..28b65b3cc 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -11,10 +11,10 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ```{nbgallery} :caption: Getting started -:name: getting-started +:name: tutorial-overview - - + + ``` @@ -26,76 +26,61 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ```{nbgallery} :caption: Set up FieldSets -:name: how-to-fieldsets - - - - - - - - - - - +:name: tutorial-fieldsets + + + + + + + + + ``` ```{nbgallery} :caption: Create ParticleSets -:name: how-to-particlesets +:name: tutorial-particlesets - + ``` ```{nbgallery} -:caption: Write a custom `Kernel` -:name: how-to-kernels - - - - -examples/how-to_sampling.ipynb -examples/how-to_gsw_density.ipynb - - - -``` - -```{nbgallery} -:caption: Write an `Interpolator` -:name: how-to-interpolators -``` - -```{nbgallery} -:caption: Run an accurate and efficient simulation -:name: how-to-simulation - - - - - +:caption: Write a custom kernel +:name: tutorial-kernels + + +examples/tutorial_sampling.ipynb +examples/tutorial_gsw_density.ipynb + + + + ``` ```{nbgallery} :caption: Other tutorials -:name: how-to-other - - - - - +:name: tutorial-other + + + + + + + + ``` ```{nbgallery} :caption: Worked examples -:name: how-to-examples +:name: tutorial-examples -examples/how-to_Argofloats.ipynb - +examples/tutorial_Argofloats.ipynb + ``` ```{toctree} :hidden: v3 to v4 migration guide Example scripts -``` \ No newline at end of file +``` From 7473293678e17e7a36074a91aeb562dce8e4c92b Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 4 Nov 2025 13:42:10 +0100 Subject: [PATCH 20/26] Fix navigation by adding scaffolding pages --- docs/getting_started/concepts_overview.md | 5 +++- docs/getting_started/index.md | 12 ++++++--- docs/getting_started/installation.md | 8 ++++-- .../getting_started/tutorial_quickstart.ipynb | 26 +++++++++++++++++++ 4 files changed, 44 insertions(+), 7 deletions(-) create mode 100644 docs/getting_started/tutorial_quickstart.ipynb diff --git a/docs/getting_started/concepts_overview.md b/docs/getting_started/concepts_overview.md index 5cbef5f08..b4cccb740 100644 --- a/docs/getting_started/concepts_overview.md +++ b/docs/getting_started/concepts_overview.md @@ -1,4 +1,7 @@ +# Parcels concepts + A markdown document explaining the core Parcels classes + ```{note} TODO: adapt from <../user_guide/examples/explanation_parcels_concepts.ipynb> -``` \ No newline at end of file +``` diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index ee741dd15..7aedc2edf 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -3,10 +3,10 @@ Getting started with parcels is easy; here you will find: ```{toctree} -The installation guide - +Installation guide +Quickstart tutorial +Parcels concepts explainer + ``` @@ -21,3 +21,7 @@ TODO: Write quickstart tutorial. This should focus on getting users familiar wit ```{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/getting_started/installation.md b/docs/getting_started/installation.md index 303b72cab..72dce9340 100644 --- a/docs/getting_started/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. @@ -31,6 +33,8 @@ conda activate parcels 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.ipynb) 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](../development/index.md#development) for development instructions. diff --git a/docs/getting_started/tutorial_quickstart.ipynb b/docs/getting_started/tutorial_quickstart.ipynb new file mode 100644 index 000000000..bb7fe3ab2 --- /dev/null +++ b/docs/getting_started/tutorial_quickstart.ipynb @@ -0,0 +1,26 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "# Quickstart tutorial\n", + "TODO: Completely rewrite examples/parcels_tutorial.ipynb into the quickstart tutorial" + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [] + } + ], + "metadata": { + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From 6cc21ea54d118ff117433e6bc6a6395dc04fe4b5 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 4 Nov 2025 15:18:27 +0100 Subject: [PATCH 21/26] add documentation notes to outline ideas for docs website and style guide --- docs/development/docsguide.md | 16 ++++++++++++++++ docs/development/index.md | 1 + 2 files changed, 17 insertions(+) create mode 100644 docs/development/docsguide.md diff --git a/docs/development/docsguide.md b/docs/development/docsguide.md new file mode 100644 index 000000000..63f38db9c --- /dev/null +++ b/docs/development/docsguide.md @@ -0,0 +1,16 @@ +# 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. \ No newline at end of file diff --git a/docs/development/index.md b/docs/development/index.md index 51998e6cf..1183eb743 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -16,6 +16,7 @@ Release Notes :hidden: maintainer +docsguide ``` ## Why contribute? From 0626bee76ef9762bc05335407259bebcecd57b40 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Tue, 4 Nov 2025 16:42:33 +0100 Subject: [PATCH 22/26] update notebook testing folder --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index bc34f87ff..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] From 8a429b7f24094df87acf807c42d1670ca66e77bf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 5 Nov 2025 12:01:16 +0000 Subject: [PATCH 23/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/development/docsguide.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/development/docsguide.md b/docs/development/docsguide.md index 63f38db9c..2735c7cb7 100644 --- a/docs/development/docsguide.md +++ b/docs/development/docsguide.md @@ -1,16 +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. \ No newline at end of file + +- 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. From 2d1ec995fcd86c019b729d241c0da889cbe57139 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Wed, 5 Nov 2025 13:31:25 +0100 Subject: [PATCH 24/26] make quickstart tutorial a .md file to keep notebooks in examples folder. --- docs/development/docsguide.md | 6 ++++- docs/getting_started/index.md | 2 +- docs/getting_started/installation.md | 2 +- .../getting_started/tutorial_quickstart.ipynb | 26 ------------------- docs/getting_started/tutorial_quickstart.md | 3 +++ docs/user_guide/index.md | 2 +- 6 files changed, 11 insertions(+), 30 deletions(-) delete mode 100644 docs/getting_started/tutorial_quickstart.ipynb create mode 100644 docs/getting_started/tutorial_quickstart.md diff --git a/docs/development/docsguide.md b/docs/development/docsguide.md index 63f38db9c..2735c7cb7 100644 --- a/docs/development/docsguide.md +++ b/docs/development/docsguide.md @@ -1,16 +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. \ No newline at end of file + +- 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/getting_started/index.md b/docs/getting_started/index.md index 7aedc2edf..eb041f1ab 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -4,7 +4,7 @@ Getting started with parcels is easy; here you will find: ```{toctree} Installation guide -Quickstart tutorial +Quickstart tutorial Parcels concepts explainer diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 72dce9340..6c25c57b4 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -33,7 +33,7 @@ conda activate parcels The next time you start a terminal and want to work with Parcels, activate the environment with `conda activate parcels`. ``` -**Step 4:** Create a Jupyter Notebook or Python script to set up your first Parcels simulation! The [quickstart tutorial](tutorial_quickstart.ipynb) 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. +**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 diff --git a/docs/getting_started/tutorial_quickstart.ipynb b/docs/getting_started/tutorial_quickstart.ipynb deleted file mode 100644 index bb7fe3ab2..000000000 --- a/docs/getting_started/tutorial_quickstart.ipynb +++ /dev/null @@ -1,26 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "0", - "metadata": {}, - "source": [ - "# Quickstart tutorial\n", - "TODO: Completely rewrite examples/parcels_tutorial.ipynb into the quickstart tutorial" - ] - }, - { - "cell_type": "markdown", - "id": "1", - "metadata": {}, - "source": [] - } - ], - "metadata": { - "language_info": { - "name": "python" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} 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/user_guide/index.md b/docs/user_guide/index.md index 28b65b3cc..c03088714 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -76,7 +76,7 @@ examples/tutorial_gsw_density.ipynb :name: tutorial-examples examples/tutorial_Argofloats.ipynb - + ``` ```{toctree} From 2bfef2f01687fcd21e260394def6e7ff96d78c85 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Wed, 5 Nov 2025 14:58:57 +0100 Subject: [PATCH 25/26] fix TrajAn link --- docs/user_guide/examples/tutorial_output.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/examples/tutorial_output.ipynb b/docs/user_guide/examples/tutorial_output.ipynb index 13778feca..da283dc1b 100644 --- a/docs/user_guide/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](https://lagrangian-diags.readthedocs.io/en/latest/index.html) project. The [TrajAn package](https://opendrift.github.io/trajan/index.html) can be used to read and plot datasets of Lagrangian trajectories." ] }, { From 3f884fd3f5c79bd11b247f07b80673970967cc85 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Wed, 5 Nov 2025 15:05:22 +0100 Subject: [PATCH 26/26] add LA Diag Cookbook link at the top of output tutorial --- docs/user_guide/examples/tutorial_output.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/examples/tutorial_output.ipynb b/docs/user_guide/examples/tutorial_output.ipynb index da283dc1b..faf5908e5 100644 --- a/docs/user_guide/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](https://opendrift.github.io/trajan/index.html) 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." ] }, {