restructure API pages to have classes on separate pages

Author: reint-fischer

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

@@ -73,7 +73,7 @@ Submodules
 
 .. toctree::
    :caption: Submodules
-   :ma: 1
+   :maxdepth: 1
 
             {% for submodule in visible_submodules %}
    {{ submodule.include_path }}
@@ -153,4 +153,4 @@ Functions
    {{ obj_item.render()|indent(3) }}
       {% endfor %}
    {% endif %}
-{% endif %}
+{% endif %}

docs/conf.py

@@ -533,16 +533,16 @@ def linkcode_resolve(domain, info):
 
 # -- Options for autoapi --------------------------------------------------
 autoapi_dirs = ["../src/parcels"]
-autoapi_add_toctree_entry = False
+# autoapi_add_toctree_entry = False
 autoapi_root = "reference"
 autoapi_options = [
     "members",
     # "show-inheritance",
-    # "undoc-members",
+    "undoc-members",
     "show-module-summary",
     "imported-members",
 ]
 autoapi_member_order = "bysource"
-autodoc_typehints = "signature"
+autodoc_typehints = "none"
 autoapi_template_dir = "_autoapi_templates"
 autoapi_own_page_level = "class"

src/parcels/_core/basegrid.py

@@ -22,6 +22,7 @@ class GridType(IntEnum):
 
 
 class BaseGrid(ABC):
+    """Docstring for Basegrid class"""
     @abstractmethod
     def search(self, z: float, y: float, x: float, ei=None) -> dict[str, tuple[int, float | np.ndarray]]:
         """

src/parcels/_core/fieldset.py

@@ -51,8 +51,8 @@ class FieldSet:
     to and what parent model the field is associated with. Parcels uses this metadata
     during execution for interpolation.  Each `UXDataArray.attributes` field dictionary
     must have:
-      * "location" key set to "face", "node", or "edge" to define which pairing of points a field is associated with.
-      * "mesh" key to define which parent model the fields are associated with (e.g. "fesom_mesh", "icon_mesh")
+    * "location" key set to "face", "node", or "edge" to define which pairing of points a field is associated with.
+    * "mesh" key to define which parent model the fields are associated with (e.g. "fesom_mesh", "icon_mesh")
 
     """