DOCS: Adopt sphinx-autoapi

.pre-commit-config.yaml

@@ -76,3 +76,11 @@ repos:
       - id: numpydoc-validation
         exclude: "^lib/iris/tests/|docs/gallery_code/"
         types: [file, python]
+
+-   repo: local
+    hooks:
+    -   id: check-attribute-comment
+        name: use triple quote docstring proceding attribute
+        types: [python]
+        entry: '#:'
+        language: pygrep

benchmarks/benchmarks/generate_data/__init__.py

@@ -26,11 +26,12 @@
 from iris._lazy_data import as_concrete_data
 from iris.fileformats import netcdf
 
-#: Python executable used by :func:`run_function_elsewhere`, set via env
-#:  variable of same name. Must be path of Python within an environment that
-#:  includes Iris (including dependencies and test modules) and Mule.
 try:
     DATA_GEN_PYTHON = environ["DATA_GEN_PYTHON"]
+    """Python executable used by :func:`run_function_elsewhere`, set via env variable of same name.
+       Must be path of Python within an environment that
+       includes Iris (including dependencies and test modules) and Mule."""
+
     _ = check_output([DATA_GEN_PYTHON, "-c", "a = True"])
 except KeyError:
     error = "Env variable DATA_GEN_PYTHON not defined."

docs/src/_autoapi_templates/python/README.md

@@ -0,0 +1,7 @@
+# ⚠️
+This directory contains templates copied from `sphinx-autoapi` 3.2.1, which have been customised for
+our own purposes.
+
+For further details, see:
+
+- https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-customise-layout-through-templates

docs/src/_autoapi_templates/python/module.rst

@@ -0,0 +1,180 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{% if obj.type is equalto("package") and obj.name is equalto("geovista") %}
+.. _gv-api:
+
+:fa:`file-lines` API Reference
+******************************
+
+GeoVista
+========
+{% else %}
+:py:mod:`{{ obj.id }}`
+=========={{ "=" * obj.id|length }}
+{% endif %}
+
+.. py:module:: {{ obj.name }}
+
+      {% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+      {% endif %}
+
+      {% block subpackages %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+         {% if visible_subpackages %}
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+            {% for subpackage in visible_subpackages %}
+   {{ subpackage.include_path }}
+            {% endfor %}
+
+
+         {% endif %}
+      {% endblock %}
+      {% block submodules %}
+         {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% if visible_submodules %}
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+            {% for submodule in visible_submodules %}
+   {{ submodule.include_path }}
+            {% endfor %}
+
+
+         {% endif %}
+      {% endblock %}
+      {% block content %}
+         {% set visible_children = obj.children|selectattr("display")|list %}
+         {% if visible_children %}
+            {% 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_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_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:
+
+                     {% for klass in visible_classes %}
+   {{ klass.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for klass in visible_classes %}
+   {{ klass.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 %}