v4 Reference API using autoapi

docs/conf.py

@@ -40,6 +40,7 @@
     "numpydoc",
     "sphinxcontrib.mermaid",
     "sphinx_design",
+    "autoapi.extension",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -528,3 +529,18 @@ def linkcode_resolve(domain, info):
 nb_execution_excludepatterns = ["jupyter_execute", ".jupyter_cache"]
 nb_execution_raise_on_error = True
 nb_execution_timeout = 75
+
+# -- Options for autoapi --------------------------------------------------
+autoapi_dirs = ["../src/parcels"]
+autoapi_add_toctree_entry = False
+autoapi_root = "reference"
+autoapi_options = [
+    "members",
+    "show-inheritance",
+    "undoc-members",
+    "show-module-summary",
+    "imported-members",
+]
+autoapi_member_order = "bysource"
+autodoc_typehints = "signature"
+#   'special-members',

docs/index.md

@@ -12,7 +12,7 @@ _Animation of virtual particles carried by ocean surface flow in the global ocea
 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)
+**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/parcels/index)
 
 `````{grid} 1 2 2 2
 :gutter: 4
@@ -94,7 +94,7 @@ Getting started <getting_started/index>
 User guide <user_guide/index>
 Community <community/index>
 Development <development/index>
-API reference <reference>
+API reference <reference/parcels/index>
 v4 <v4/index>
 Parcels website <https://parcels-code.org/>
 ```

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 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.
+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/parcels/index). 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.

pixi.toml

@@ -82,6 +82,7 @@ matplotlib-base = ">=2.0.2"
 gsw = "*"
 
 [feature.docs.dependencies]
+parcels = { path = "." }
 numpydoc = "!=1.9.0"
 myst-nb = "*"
 ipython = "*"
@@ -91,6 +92,7 @@ pydata-sphinx-theme = "*"
 sphinx-autobuild = "*"
 sphinxcontrib-mermaid = "*"
 sphinx-design = "*"
+sphinx-autoapi = "*"
 
 [feature.docs.tasks]
 docs = "sphinx-build docs docs/_build"

pyproject.toml

@@ -110,12 +110,6 @@ ignore = [
   # 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
@@ -131,6 +125,17 @@ ignore = [
   "F811",
 ]
 
+# [tool.ruff.lint.per-file-ignores]
+# # Ignore docstring rules everywhere except for the stable files (particleset.py, interpolators.py).
+# "!src/parcels/{_core/particleset,interpolators}.py" = [
+#   # Missing docstring in public class
+#   "D101",
+#   # Missing docstring in public method
+#   "D102",
+#   # Missing docstring in public function
+#   "D103",
+# ]
+
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
 

src/parcels/_core/basegrid.py

@@ -1,3 +1,5 @@
+"""Module defining the BaseGrid class for XGrid and UXGrid"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod