Summary API Docs

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  - pull_request
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install Dependencies
+        run: pip install -e . -r dev-requirements.txt
+
+      - name: Print installed packages
+        run: pip freeze
+
+      - name: Build docs with Sphinx
+        working-directory: ./docs/
+        run: make html
+
+      - name: Check public API docs are complete
+        working-directory: ./docs/
+        run: python check_public_api.py

dev-requirements.txt

@@ -22,6 +22,7 @@ attrs==25.3.0
     # via
     #   jsonschema
     #   referencing
+    #   sphobjinv
 autodocsumm==0.2.14
     # via sphinx-toolbox
 babel==2.17.0
@@ -37,6 +38,7 @@ certifi==2025.7.14
     #   requests
     #   sentry-sdk
     #   sphinx-prompt
+    #   sphobjinv
 charset-normalizer==3.4.2
     # via requests
 click==8.2.1
@@ -140,7 +142,9 @@ jinja2==3.1.6
     #   sphinx-autoapi
     #   sphinx-jinja2-compat
 jsonschema==4.24.1
-    # via labthings-fastapi (pyproject.toml)
+    # via
+    #   labthings-fastapi (pyproject.toml)
+    #   sphobjinv
 jsonschema-specifications==2025.4.1
     # via jsonschema
 markdown-it-py==3.0.0
@@ -309,6 +313,8 @@ sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
+sphobjinv==2.4
+    # via labthings-fastapi (pyproject.toml)
 starlette==0.47.1
     # via fastapi
 tabulate==0.9.0

docs/autoapi_templates/index.rst

@@ -0,0 +1,13 @@
+Internal API Reference
+======================
+
+This page contains auto-generated API reference documentation [#f1]_. Most users should find the :ref:`public_api` more useful.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages|selectattr("is_top_level_object") %}
+   {{ page.include_path }}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

docs/autoapi_templates/python/attribute.rst

@@ -0,0 +1 @@
+{% extends "python/data.rst" %}

docs/autoapi_templates/python/class.rst

@@ -0,0 +1,104 @@
+{% 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_attributes = own_page_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 %}
+      {% set visible_methods = own_page_children|selectattr("type", "equalto", "method")|list %}
+      {% if visible_methods %}
+Methods
+-------
+
+.. autoapisummary::
+
+            {% for method in visible_methods %}
+   {{ method.id }}
+            {% endfor %}
+
+
+      {% endif %}
+   {% endif %}
+{% endif %}

docs/autoapi_templates/python/data.rst

@@ -0,0 +1,45 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{{ obj.id }}
+{{ "=" * obj.id | length }}
+
+   {% endif %}
+.. py:{% if obj.is_type_alias() %}type{% else %}{{ obj.type }}{% endif %}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.name }}{% endif %}
+   {% if obj.is_type_alias() %}
+      {% if obj.value %}
+
+   :canonical: {{ obj.value }}
+      {% endif %}
+   {% else %}
+      {% if obj.annotation is not none %}
+
+   :type: {% if obj.annotation %} {{ obj.annotation }}{% endif %}
+      {% endif %}
+      {% if obj.value is not none %}
+
+         {% if obj.value.splitlines()|count > 1 %}
+   :value: Multiline-String
+
+   .. raw:: html
+
+      <details><summary>Show Value</summary>
+
+   .. code-block:: python
+
+      {{ obj.value|indent(width=6,blank=true) }}
+
+   .. raw:: html
+
+      </details>
+
+         {% else %}
+   :value: {{ obj.value|truncate(100) }}
+         {% endif %}
+      {% endif %}
+   {% endif %}
+
+   {% if obj.docstring %}
+
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+{% endif %}

docs/autoapi_templates/python/exception.rst

@@ -0,0 +1 @@
+{% extends "python/class.rst" %}

docs/autoapi_templates/python/function.rst

@@ -0,0 +1,21 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{{ obj.id }}
+{{ "=" * obj.id | length }}
+
+   {% endif %}
+.. py:function:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
+   {% for (args, return_annotation) in obj.overloads %}
+
+                 {%+ if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+   {% endfor %}
+   {% for property in obj.properties %}
+
+   :{{ property }}:
+   {% endfor %}
+
+   {% if obj.docstring %}
+
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+{% endif %}

docs/autoapi_templates/python/method.rst

@@ -0,0 +1,21 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{{ obj.id }}
+{{ "=" * obj.id | length }}
+
+   {% endif %}
+.. py:method:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
+   {% for (args, return_annotation) in obj.overloads %}
+
+               {%+ if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+   {% endfor %}
+   {% for property in obj.properties %}
+
+   :{{ property }}:
+   {% endfor %}
+
+   {% if obj.docstring %}
+
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+{% endif %}