From 7dc8a9c36e59247b91308685c3bfca9e285bb854 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Fri, 19 Dec 2025 15:20:52 +0100 Subject: [PATCH 1/6] add reference API links to quickstart tutorial --- docs/getting_started/index.md | 4 ---- docs/getting_started/tutorial_quickstart.md | 20 ++++++++------------ 2 files changed, 8 insertions(+), 16 deletions(-) diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index f643d5bfc5..3f3955d67c 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -9,7 +9,3 @@ Getting started with parcels is easy; here you will find: 🎓 Output tutorial 📖 Conceptual workflow ``` - -```{note} -TODO: Add links to Reference API in quickstart tutorial and concepts explanation -``` diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md index 038302c225..9f364e839e 100644 --- a/docs/getting_started/tutorial_quickstart.md +++ b/docs/getting_started/tutorial_quickstart.md @@ -41,8 +41,8 @@ ds_fields As we can see, the reanalysis dataset contains eastward velocity `uo`, northward velocity `vo`, potential temperature (`thetao`) and salinity (`so`) fields. -These hydrodynamic fields need to be stored in a `parcels.FieldSet` object. Parcels provides tooling to parse many types -of models or observations into such a `parcels.FieldSet` object. Here, we use `FieldSet.from_copernicusmarine()`, which +These hydrodynamic fields need to be stored in a {py:obj}`parcels.FieldSet` object. Parcels provides tooling to parse many types +of models or observations into such a `parcels.FieldSet` object. Here, we use {py:obj}`FieldSet.from_copernicusmarine()`, which recognizes the standard names of a velocity field: ```{code-cell} @@ -61,10 +61,10 @@ velocity = ds_fields.isel(time=0, depth=0).plot.quiver(x="longitude", y="latitud Now that we have created a `parcels.FieldSet` object from the hydrodynamic data, we need to provide our second input: the virtual particles for which we will calculate the trajectories. -We need to create a `parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet` +We need to create a {py:obj}`parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet` object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of -`parcels.Particle` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add -other `Variables` such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb). +{py:obj}`parcels.ParticleClass` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add +other {py:obj}`parcels.Variable`s such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb). ```{code-cell} # Particle locations and initial time @@ -90,7 +90,7 @@ ax.scatter(lon,lat,s=40,c='w',edgecolors='r'); ## Compute: `Kernel` After setting up the input data and particle start locations and times, we need to specify what calculations to do with -the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on +the particles. These calculations, or numerical integrations, will be performed by what we call a {py:obj}`parcels.Kernel`, operating on all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. Parcels comes with a number of standard kernels, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`: @@ -105,7 +105,7 @@ kernels = [parcels.kernels.AdvectionRK2] ## Prepare output: `ParticleFile` Before starting the simulation, we must define where and how frequent we want to write the output of our simulation. -We can define this in a `ParticleFile` object: +We can define this in a {py:obj}`parcels.ParticleFile` object: ```{code-cell} output_file = parcels.ParticleFile("output-quickstart.zarr", outputdt=np.timedelta64(1, "h")) @@ -117,7 +117,7 @@ the `outputdt` argument so that it captures the smallest timescales of our inter ## Run Simulation: `ParticleSet.execute()` -Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`. +Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`. This is done using the {py:meth}`parcels.ParticleSet.execute()` method. Additionally, we need to specify: - the `runtime`: for how long we want to simulate particles. @@ -125,10 +125,6 @@ Additionally, we need to specify: integration scheme, the accuracy of our simulation will depend on `dt`. Read [this notebook](https://github.com/Parcels-code/10year-anniversary-session2/blob/8931ef69577dbf00273a5ab4b7cf522667e146c5/advection_and_windage.ipynb) to learn more about numerical accuracy. -```{note} -TODO: add Michaels 10-years Parcels notebook to the user guide -``` - ```{code-cell} :tags: [hide-output] pset.execute( From 79b00f53e6e2981574be8d5bfddc91af32f3d1ca Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Fri, 19 Dec 2025 16:20:15 +0100 Subject: [PATCH 2/6] remove user guide todo note --- docs/user_guide/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 8bbb416514..a8975a06aa 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -17,10 +17,6 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ## How to -```{note} -TODO: Add links to Reference API throughout -``` - ```{note} **Migrate from v3 to v4** using [this migration guide](v4-migration.md) ``` From 6ea5459311cf672839c95d6fc6378ef81e6edc00 Mon Sep 17 00:00:00 2001 From: reint-fischer Date: Fri, 19 Dec 2025 16:24:57 +0100 Subject: [PATCH 3/6] add parcels.kernels link --- docs/getting_started/tutorial_quickstart.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md index 9f364e839e..d79283a106 100644 --- a/docs/getting_started/tutorial_quickstart.md +++ b/docs/getting_started/tutorial_quickstart.md @@ -92,11 +92,7 @@ ax.scatter(lon,lat,s=40,c='w',edgecolors='r'); After setting up the input data and particle start locations and times, we need to specify what calculations to do with the particles. These calculations, or numerical integrations, will be performed by what we call a {py:obj}`parcels.Kernel`, operating on all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. -Parcels comes with a number of standard kernels, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`: - -```{note} -TODO: link to a list of included kernels -``` +Parcels comes with a number of common {py:obj}`parcels.kernels`, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`: ```{code-cell} kernels = [parcels.kernels.AdvectionRK2] From 5bd7e88a97692bac8355b99ab39b2b353f2c19cc Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Tue, 23 Dec 2025 17:16:00 +0100 Subject: [PATCH 4/6] small fixes to API reference --- docs/getting_started/tutorial_quickstart.md | 2 +- src/parcels/_datasets/__init__.py | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md index d79283a106..30cbe082b2 100644 --- a/docs/getting_started/tutorial_quickstart.md +++ b/docs/getting_started/tutorial_quickstart.md @@ -92,7 +92,7 @@ ax.scatter(lon,lat,s=40,c='w',edgecolors='r'); After setting up the input data and particle start locations and times, we need to specify what calculations to do with the particles. These calculations, or numerical integrations, will be performed by what we call a {py:obj}`parcels.Kernel`, operating on all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. -Parcels comes with a number of common {py:obj}`parcels.kernels`, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`: +Parcels comes with a number of common {py:obj}`parcels.kernels`, from which we will use the Runge-Kutta advection kernel {py:obj}`parcels.kernels.AdvectionRK2`: ```{code-cell} kernels = [parcels.kernels.AdvectionRK2] diff --git a/src/parcels/_datasets/__init__.py b/src/parcels/_datasets/__init__.py index 6e57e69507..8a82843b1f 100644 --- a/src/parcels/_datasets/__init__.py +++ b/src/parcels/_datasets/__init__.py @@ -11,8 +11,7 @@ Developers, note that you should only add functions that create idealised datasets to this subpackage if they are (a) quick to generate, and (b) only use dependencies already shipped with Parcels. No data files should be added to this subpackage. Real world data files should be added to the `Parcels-code/parcels-data` repository on GitHub. -Parcels Dataset Philosophy -------------------------- +**Parcels Dataset Philosophy** When adding datasets, there may be a tension between wanting to add a specific dataset or wanting to add machinery to generate completely parameterised datasets (e.g., with different grid resolutions, with different ranges, with different datetimes etc.). There are trade-offs to both approaches: @@ -31,8 +30,7 @@ Sometimes we may want to test Parcels against a whole range of datasets varying in a certain way - to ensure Parcels works as expected. For these, we should add machinery to create generated datasets. -Structure --------- +**Structure** This subpackage is broken down into structured and unstructured parts. Each of these have common submodules: From fb29e515b23c65ca2e0f83c345571b7c49c95ffb Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Tue, 23 Dec 2025 17:26:33 +0100 Subject: [PATCH 5/6] fixing rst parsing error --- src/parcels/_core/basegrid.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/parcels/_core/basegrid.py b/src/parcels/_core/basegrid.py index af64e71092..05649436d5 100644 --- a/src/parcels/_core/basegrid.py +++ b/src/parcels/_core/basegrid.py @@ -60,6 +60,7 @@ def search(self, z: float, y: float, x: float, ei=None) -> dict[str, tuple[int, - Unstructured grid: {"Z": (zi, zeta), "FACE": (fi, bcoords)} Where: + - index (int): The cell position of the particles along the given axis - barycentric_coordinates (float or np.ndarray): The coordinates defining the particles positions within the grid cell. For structured grids, this From 3d38eb6ce193c77ad8aea49a5bbdf948b72bff99 Mon Sep 17 00:00:00 2001 From: Nick Hodgskin <36369090+VeckoTheGecko@users.noreply.github.com> Date: Mon, 12 Jan 2026 16:00:43 +0100 Subject: [PATCH 6/6] Remove sphinx autoapi templates (#2464) Co-authored-by: Erik van Sebille Fixes #2448 --- docs/_autoapi_templates/python/class.rst | 96 ------------- docs/_autoapi_templates/python/module.rst | 152 -------------------- docs/conf.py | 2 - docs/getting_started/tutorial_quickstart.md | 2 +- 4 files changed, 1 insertion(+), 251 deletions(-) delete mode 100644 docs/_autoapi_templates/python/class.rst delete mode 100644 docs/_autoapi_templates/python/module.rst diff --git a/docs/_autoapi_templates/python/class.rst b/docs/_autoapi_templates/python/class.rst deleted file mode 100644 index 5fa91e1d03..0000000000 --- a/docs/_autoapi_templates/python/class.rst +++ /dev/null @@ -1,96 +0,0 @@ -{# Adapted from sphinx-autoapi https://github.com/readthedocs/sphinx-autoapi #} -{% if obj.display %} - {% if is_own_page %} -{{ obj.id }} -{{ "=" * obj.id | length }} - {% endif %} - {% set visible_children = obj.children|selectattr("display")|list %} - {% set own_page_children = visible_children|selectattr("type", "in", own_page_types)|list %} - {% if is_own_page and own_page_children %} -.. toctree:: - :hidden: - {% for child in own_page_children %} - {{ child.include_path }} - {% endfor %} - {% endif %} -.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}{% if obj.args %}({{ obj.args }}){% endif %} - - {% for (args, return_annotation) in obj.overloads %} - {{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %} - - {% endfor %} - {% if obj.bases %} - {% if "show-inheritance" in autoapi_options %} - - Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %} - {% endif %} - {% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %} - .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }} - :parts: 1 - {% if "private-members" in autoapi_options %} - :private-bases: - {% endif %} - - {% endif %} - {% endif %} - {% if obj.docstring %} - {{ obj.docstring|indent(3) }} - {% endif %} - {% for obj_item in visible_children %} - {% if obj_item.type not in own_page_types %} -{{ obj_item.render()|indent(3) }} - {% endif %} - {% endfor %} - {% if is_own_page and own_page_children %} - {% set visible_methods = visible_children|selectattr("type", "equalto", "method")|list %} - {% if visible_methods %} -Methods -------- - -.. autoapisummary:: - - {% for method in visible_methods %} - {{ method.id }} - {% endfor %} - - - {% endif %} - {% set visible_attributes = visible_children|selectattr("type", "equalto", "attribute")|list %} - {% if visible_attributes %} -Attributes ----------- - -.. autoapisummary:: - - {% for attribute in visible_attributes %} - {{ attribute.id }} - {% endfor %} - - - {% endif %} - {% set visible_exceptions = own_page_children|selectattr("type", "equalto", "exception")|list %} - {% if visible_exceptions %} -Exceptions ----------- - -.. autoapisummary:: - - {% for exception in visible_exceptions %} - {{ exception.id }} - {% endfor %} - - - {% endif %} - {% set visible_classes = own_page_children|selectattr("type", "equalto", "class")|list %} - {% if visible_classes %} -Classes -------- - -.. autoapisummary:: - - {% for klass in visible_classes %} - {{ klass.id }} - {% endfor %} - {% endif %} - {% endif %} -{% endif %} diff --git a/docs/_autoapi_templates/python/module.rst b/docs/_autoapi_templates/python/module.rst deleted file mode 100644 index 659cfa6384..0000000000 --- a/docs/_autoapi_templates/python/module.rst +++ /dev/null @@ -1,152 +0,0 @@ -{# Adapted from sphinx-autoapi https://github.com/readthedocs/sphinx-autoapi #} -{% if obj.display %} - {% if is_own_page %} -{{ obj.id }} -{{ "=" * obj.id|length }} - -.. py:module:: {{ obj.name }} - - {% if obj.docstring %} -.. autoapi-nested-parse:: - - {{ obj.docstring|indent(3) }} - - {% endif %} - - {% block content %} - {% set visible_children = obj.children|selectattr("display")|list %} - {% if visible_children %} - {% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} - {% if visible_classes %} - {% if "class" in own_page_types or "show-module-summary" in autoapi_options %} -Classes -------- - - {% if "class" in own_page_types %} -.. toctree:: - :hidden: - :caption: Classes - - {% for klass in visible_classes %} - {{ klass.include_path }} - {% endfor %} - - {% endif %} -.. autoapisummary:: - - {% for klass in visible_classes %} - {{ klass.id }} - {% endfor %} - {% endif %} - - - {% endif %} - {% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %} - {% if visible_exceptions %} - {% if "exception" in own_page_types or "show-module-summary" in autoapi_options %} -Exceptions ----------- - - {% if "exception" in own_page_types %} -.. toctree:: - :hidden: - - {% for exception in visible_exceptions %} - {{ exception.include_path }} - {% endfor %} - - {% endif %} -.. autoapisummary:: - - {% for exception in visible_exceptions %} - {{ exception.id }} - {% endfor %} - {% endif %} - - - {% endif %} - {% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %} - {% if visible_attributes %} - {% if "attribute" in own_page_types or "show-module-summary" in autoapi_options %} -Attributes ----------- - - {% if "attribute" in own_page_types %} -.. toctree:: - :hidden: - - {% for attribute in visible_attributes %} - {{ attribute.include_path }} - {% endfor %} - - {% endif %} -.. autoapisummary:: - - {% for attribute in visible_attributes %} - {{ attribute.id }} - {% endfor %} - {% endif %} - - - {% endif %} - {% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} - {% if visible_functions %} - {% if "function" in own_page_types or "show-module-summary" in autoapi_options %} -Functions ---------- - - {% if "function" in own_page_types %} -.. toctree:: - :hidden: - - {% for function in visible_functions %} - {{ function.include_path }} - {% endfor %} - - {% endif %} -.. autoapisummary:: - - {% for function in visible_functions %} - {{ function.id }} - {% endfor %} - {% endif %} - - - {% endif %} - {% set visible_subpackages = obj.subpackages|selectattr("display")|list %} - {% set visible_submodules = obj.submodules|selectattr("display")|list %} - {% set visible_submodules = (visible_subpackages + visible_submodules)|sort %} - {% if visible_submodules %} -.. toctree:: - :caption: Submodules - :maxdepth: 1 - - {% for submodule in visible_submodules %} - {{ submodule.include_path }} - {% endfor %} - {% endif %} - {% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %} - {% if this_page_children %} -{{ obj.type|title }} Contents -{{ "-" * obj.type|length }}--------- - - {% for obj_item in this_page_children %} -{{ obj_item.render()|indent(0) }} - {% endfor %} - {% endif %} - {% endif %} - {% endblock %} - {% else %} -.. py:module:: {{ obj.name }} - - {% if obj.docstring %} - .. autoapi-nested-parse:: - - {{ obj.docstring|indent(6) }} - - {% endif %} - {% for obj_item in visible_children %} - {{ obj_item.render()|indent(3) }} - {% endfor %} - {% endif %} -{% endif %} diff --git a/docs/conf.py b/docs/conf.py index debbc39b15..6d044def40 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,7 +116,6 @@ # directories to ignore when looking for source files. exclude_patterns = [ "_build", - "_autoapi_templates", "jupyter_execute", "**.ipynb_checkpoints", "user_guide/examples_v3", @@ -544,5 +543,4 @@ def linkcode_resolve(domain, info): ] autoapi_member_order = "bysource" autodoc_typehints = "none" -autoapi_template_dir = "_autoapi_templates" autoapi_own_page_level = "class" diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md index 30cbe082b2..b843ea9df5 100644 --- a/docs/getting_started/tutorial_quickstart.md +++ b/docs/getting_started/tutorial_quickstart.md @@ -42,7 +42,7 @@ As we can see, the reanalysis dataset contains eastward velocity `uo`, northward (`thetao`) and salinity (`so`) fields. These hydrodynamic fields need to be stored in a {py:obj}`parcels.FieldSet` object. Parcels provides tooling to parse many types -of models or observations into such a `parcels.FieldSet` object. Here, we use {py:obj}`FieldSet.from_copernicusmarine()`, which +of models or observations into such a `parcels.FieldSet` object. Here, we use {py:func}`parcels.FieldSet.from_copernicusmarine()`, which recognizes the standard names of a velocity field: ```{code-cell}