adopt latest sphinx-autoapi templates (#1053)

changelog/1039.dependency.rst

@@ -1,2 +1,2 @@
-Introduced temporary maximum pin ``towncrier<24.7.0`` due to breaking change
+Introduced temporary maximum pin ``towncrier <24.7.0`` due to breaking change
 for ``sphinx-changelog``. (:user:`bjlittle`)

changelog/1040.dependency.rst

@@ -1,2 +1,2 @@
 Bumped ``mambaforge`` from 22.9 to 23.11 for ``readthedocs`` and introduced
-minimum pin ``lazy_loader>=0.4``. (:user:`bjlittle`)
+minimum pin ``lazy_loader >=0.4``. (:user:`bjlittle`)

changelog/1053.documentation.rst

@@ -0,0 +1,2 @@
+Adopted `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`__ 3.2.1 templates.
+(:user:`bjlittle`)

docs/src/_autoapi_templates/python/README.md

@@ -1,5 +1,5 @@
 # ⚠️
-This directory contains templates copied from `sphinx-autoapi` 3.0.0, which have been customised for
+This directory contains templates copied from `sphinx-autoapi` 3.2.1, which have been customised for
 our own purposes.
 
 For further details, see:

docs/src/_autoapi_templates/python/module.rst

@@ -1,121 +1,177 @@
-{% if not obj.display %}
-:orphan:
-
-{% endif %}
+{% 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
 ******************************
 
 {% endif %}
-:py:mod:`{{ obj.name }}`
-=========={{ "=" * obj.name|length }}
+{{ obj.id }}
+{{ "=" * obj.id|length }}
 
 .. py:module:: {{ obj.name }}
 
-{% if obj.docstring %}
+      {% if obj.docstring %}
 .. autoapi-nested-parse::
 
    {{ obj.docstring|indent(3) }}
 
-{% endif %}
+      {% endif %}
 
-{% block subpackages %}
-{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
-{% if visible_subpackages %}
+      {% block subpackages %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+         {% if visible_subpackages %}
 Subpackages
 -----------
+
 .. toctree::
-   :titlesonly:
-   :maxdepth: 3
+   :maxdepth: 1
 
-{% for subpackage in visible_subpackages %}
-   {{ subpackage.short_name }}/index.rst
-{% endfor %}
+            {% for subpackage in visible_subpackages %}
+   {{ subpackage.include_path }}
+            {% endfor %}
 
 
-{% endif %}
-{% endblock %}
-{% block submodules %}
-{% set visible_submodules = obj.submodules|selectattr("display")|list %}
-{% if visible_submodules %}
+         {% endif %}
+      {% endblock %}
+      {% block submodules %}
+         {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% if visible_submodules %}
 Submodules
 ----------
+
 .. toctree::
-   :titlesonly:
    :maxdepth: 1
 
-{% for submodule in visible_submodules %}
-   {{ submodule.short_name }}/index.rst
-{% endfor %}
+            {% for submodule in visible_submodules %}
+   {{ submodule.include_path }}
+            {% endfor %}
 
 
-{% endif %}
-{% endblock %}
-{% block content %}
-{% if obj.all is not none %}
-{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
-{% elif obj.type is equalto("package") %}
-{% set visible_children = obj.children|selectattr("display")|list %}
-{% else %}
-{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
-{% endif %}
-{% if visible_children %}
-{{ obj.type|title }} Contents
-{{ "-" * obj.type|length }}---------
+         {% 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
+----------
 
-{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
-{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
-{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
-{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
-{% block classes scoped %}
-{% if visible_classes %}
-Classes
-~~~~~~~
+                  {% if "attribute" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for attribute in visible_attributes %}
+   {{ attribute.include_path }}
+                     {% endfor %}
 
+                  {% endif %}
 .. autoapisummary::
 
-{% for klass in visible_classes %}
-   {{ klass.id }}
-{% endfor %}
+                  {% for attribute in visible_attributes %}
+   {{ attribute.id }}
+                  {% endfor %}
+               {% endif %}
 
 
-{% endif %}
-{% endblock %}
+            {% 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
+----------
 
-{% block functions scoped %}
-{% if visible_functions %}
-Functions
-~~~~~~~~~
+                  {% if "exception" in own_page_types %}
+.. toctree::
+   :hidden:
 
+                     {% for exception in visible_exceptions %}
+   {{ exception.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
 .. autoapisummary::
 
-{% for function in visible_functions %}
-   {{ function.id }}
-{% endfor %}
+                  {% for exception in visible_exceptions %}
+   {{ exception.id }}
+                  {% endfor %}
+               {% endif %}
 
 
-{% endif %}
-{% endblock %}
+            {% 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
+-------
 
-{% block attributes scoped %}
-{% if visible_attributes %}
-Attributes
-~~~~~~~~~~
+                  {% if "class" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for klass in visible_classes %}
+   {{ klass.include_path }}
+                     {% endfor %}
 
+                  {% endif %}
 .. autoapisummary::
 
-{% for attribute in visible_attributes %}
-   {{ attribute.id }}
-{% endfor %}
+                  {% for klass in visible_classes %}
+   {{ klass.id }}
+                  {% endfor %}
+               {% endif %}
 
 
-{% endif %}
-{% endblock %}
-{% endif %}
-{% for obj_item in visible_children %}
+            {% 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 %}
+               {% 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 %}
-{% endblock %}