Further cleanup of the tutorials

[erikvansebille]

Description

This PR further cleans the documentation; mostly by adding {p:obj} and {py:func} MyST tags for links to the API. But is also provides other small fixes that I stumbled upon as I went through the documentation one more time before release

Checklist

• Contributes to Updating parcels website and documentation for v4 preview release #2702
• Closes DOC: Add cross-references from tutorials to API #2449
• This PR targets the correct branch (main for normal development, v3-support for v3 support)

AI Disclosure

None

[VeckoTheGecko]

Looked though everything. Great to have cross-refs! Can you update the list accordingly in #2449 (or, if you feel so, maybe this PR closes that too).

I've added some comments - feel free to respond to them and merge as you see fit

[VeckoTheGecko]

nit: Maybe we should also add a note here that that this is quite internal?

while {py:obj}`parcels.UxGrid` objects are based on [`uxarray.Grid`](https://uxarray.readthedocs.io/en/stable/generated/uxarray.Grid.html#uxarray.Grid) objects.

+ The user doesn't need to manually construct or manage grids - this is done internally by Parcels. When using {py:obj}`parcels.FieldSet.from_sgrid_conventions()` or {py:obj}`parcels.FieldSet.from_ugrid_conventions()` the correct grid object is constructed for your data.

[erikvansebille]

Added in 30a7cd4

[VeckoTheGecko]

Wondering about these ignores for class and mod?

[erikvansebille]

These come from warnings in the docstrings themselves. If I don't add these ignore rules, I get the following output. I didn't want to deal with them in the PR - and am not sure we should in another?

/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: parcels.spatialhash.SpatialHash [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: uxarray.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:139: WARNING: py:class reference target not found: parcels.field.Field [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:194: WARNING: py:class reference target not found: parcels._core.basegrid.BaseGrid [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: uxarray.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: file-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: default: sys.stdout [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: PathLike [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: {"zstd" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "gzip" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "snappy" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "brotli" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: None} [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: {None [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "w"} [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: parcels.particle.Particle [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:15: WARNING: py:mod reference target not found: parcels.particle.Particle [ref.mod]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: datetime.timedelta [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: parcels.fieldset.FieldSet [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: datetime.timedelta [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:240: WARNING: py:class reference target not found: parcels.kernel.Kernel [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: runtime [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.timedelta64 or [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: endtime [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.datetime64 or [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:62: WARNING: py:class reference target not found: _UXGRID_AXES [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Variable.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Variable.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:50: WARNING: py:class reference target not found: parcels._typing.VectorType [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:37: WARNING: py:class reference target not found: parcels._typing.XgridAxis [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: _XGRID_AXES [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: PathLike [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: pd.DataFrame [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: Path [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: Path [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:15:<autosummary>:1: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:49: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:17: WARNING: py:class reference target not found: xarray.Dataset [ref.class]

[erikvansebille]

Can you update the list accordingly in #2449 (or, if you feel so, maybe this PR closes that too).

Good point! This PR indeed implements cross-references on all tutorials, so closes #2449