v4 Reference API using autoapi

docs/_autoapi_templates/python/class.rst

@@ -0,0 +1,95 @@
+{% 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 %}

docs/_autoapi_templates/python/module.rst

@@ -0,0 +1,156 @@
+{% 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_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 %}
+Submodules
+----------
+
+.. toctree::
+   :caption: Submodules
+   :maxdepth: 1
+
+            {% for submodule in visible_submodules %}
+   {{ submodule.include_path }}
+            {% endfor %}
+
+
+         {% 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 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 %}

docs/conf.py

@@ -1,4 +1,4 @@
-"""Sphinx configuration file for Parcels documentation."""
+"""autoSphinx configuration file for Parcels documentation."""
 # parcels documentation build configuration file, created by
 # sphinx-quickstart on Tue Oct 20 09:58:20 2015.
 #
@@ -40,6 +40,7 @@
     "numpydoc",
     "sphinxcontrib.mermaid",
     "sphinx_design",
+    "autoapi.extension",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -115,6 +116,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = [
     "_build",
+    "_autoapi_templates",
     "jupyter_execute",
     "**.ipynb_checkpoints",
     "user_guide/examples_v3",
@@ -528,3 +530,19 @@ 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 = "none"
+autoapi_template_dir = "_autoapi_templates"
+autoapi_own_page_level = "class"

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/>
 ```

pixi.toml

@@ -73,6 +73,7 @@ matplotlib-base = ">=2.0.2"
 gsw = "*"
 
 [feature.docs.dependencies]
+parcels = { path = "." }
 numpydoc = "!=1.9.0"
 myst-nb = "*"
 ipython = "*"
@@ -82,6 +83,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/basegrid,_core/field,_core/fieldset,_core/kernel,_core/particle,_core/particlefile,_core/particleset,_core/uxgrid,_core/xgrid,kernels/advection,kernels/advectiondiffusion,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"