Add a CI check for the public API

This builds the docs in CI, and then checks the `lt` symbols against our top-level `__all__`. Hopefully, doing so will stop things getting out of date.

Author: rwb27

.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/check_public_api.py

@@ -0,0 +1,32 @@
+"""Check public API for completeness.
+
+This module loads the intersphinx inventory, and checks that all the symbols from the
+top-level module are present. This should prevent that page from going out of date.
+"""
+
+import sphobjinv as soi
+
+import labthings_fastapi as lt
+
+if __name__ == "__main__":
+    inventory = soi.Inventory("build/html/objects.inv")
+
+    if not inventory.project == "labthings-fastapi":
+        raise AssertionError(f"The inventory is for {inventory.project} not LabThings!")
+
+    published_lt_namespace = {}
+
+    for object in inventory.objects:
+        if object.name.startswith("lt.") and object.domain == "py":
+            published_lt_namespace[object.name] = object
+
+    missing = []
+
+    for name in lt.__all__:
+        if f"lt.{name}" not in published_lt_namespace:
+            missing.append(name)
+
+    if missing:
+        msg = "Failure: the following symbols are missing from the `lt` namespace: \n\n"
+        msg += "\n".join(missing)
+        raise AssertionError(msg)

pyproject.toml

@@ -41,6 +41,7 @@ dev = [
   "sphinx>=7.2",
   "sphinx-autoapi",
   "sphinx-toolbox",
+  "sphobjinv",
   "tomli; python_version < '3.11'",
   "codespell",
 ]