Changes for sphinx-autoapi + simplify conf.py

sot · Jan 24, 2025 · 871ac5a · 871ac5a
1 parent 623b4a9
commit 871ac5a
Show file tree

Hide file tree

Showing 11 changed files with 140 additions and 98 deletions.
diff --git a/docs/_templates/python/module.rst b/docs/_templates/python/module.rst
@@ -0,0 +1,126 @@
+{% 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 submodules %}
+         {% 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::
+   :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_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 %}
+
+         {% 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 %}
diff --git a/docs/api/api_commands.rst b/docs/api/api_commands.rst
diff --git a/docs/api/api_events.rst b/docs/api/api_events.rst
diff --git a/docs/api/api_occweb.rst b/docs/api/api_occweb.rst
diff --git a/docs/api/api_states.rst b/docs/api/api_states.rst
diff --git a/docs/api/api_validation.rst b/docs/api/api_validation.rst
diff --git a/docs/api/index.rst b/docs/api/index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,8 +4,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import importlib
+import os
 import sys
-from pathlib import Path
+
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -15,8 +16,7 @@
 author = 'Tom Aldcroft'
 
 # -- Path setup --------------------------------------------------------------
-rootpath = Path(__file__).resolve().parents[1]
-sys.path.insert(0, str(rootpath))
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -29,7 +29,8 @@
               'sphinx.ext.viewcode',
               'sphinx_copybutton',
               'matplotlib.sphinxext.plot_directive',
-              'numpydoc'
+              'numpydoc',
+              'autoapi.extension',
              ]
 
 templates_path = ['_templates']
@@ -94,3 +95,9 @@
 intersphinx_mapping = {
     'numpy': ('http://docs.scipy.org/doc/numpy/', None),
     }
+
+autoapi_dirs = [f"../{project}"]
+autoapi_root = "api"
+autoapi_template_dir = "_templates"
+autoapi_own_page_level = "function"
+autoapi_ignore = ["*/test_*.py", "*/conftest.py"]
diff --git a/kadi/events/json_field.py b/kadi/events/json_field.py
@@ -5,8 +5,7 @@
 more information.
 
 Taken from:
-https://github.com/django-extensions/django-extensions/
-        blob/master/django_extensions/db/fields/json.py
+https://github.com/django-extensions/django-extensions/blob/master/django_extensions/db/fields/json.py
 
  from django.db import models
  from django_extensions.db.fields import json

diff --git a/kadi/scripts/update_cmds_v2.py b/kadi/scripts/update_cmds_v2.py
@@ -9,7 +9,7 @@
 
 def get_opt(args=None):
     """
-    Get options for command line interface to update_
+    Get options for command line interface to update.
     """
     parser = argparse.ArgumentParser(description="Update HDF5 cmds v2 table")
     parser.add_argument("--lookback", type=int, help="Lookback (default=30 days)")

diff --git a/kadi/scripts/update_events.py b/kadi/scripts/update_events.py
@@ -60,7 +60,7 @@ def try4times(func, *arg, **kwarg):
 
     This is presumably due to read activity.  Not completely understood.
 
-    This function will try to run func(*arg, **kwarg) a total of 4 times with an
+    This function will try to run ``func(*arg, **kwarg)`` a total of 4 times with an
     increasing sequence of wait times between tries.  It catches only a database
     locked error.
     """