Use sphinx-toolbox to provide decorator links.

:deco: now correctly formats cross-references as `@whatever` in the docs.

Author: rwb27

dev-requirements.txt

@@ -10,20 +10,31 @@ anyio==4.9.0
     #   httpx
     #   starlette
     #   watchfiles
+apeye==1.4.1
+    # via sphinx-toolbox
+apeye-core==1.1.5
+    # via apeye
 astroid==3.3.11
     # via sphinx-autoapi
 attrs==25.3.0
     # via
     #   jsonschema
     #   referencing
+autodocsumm==0.2.14
+    # via sphinx-toolbox
 babel==2.17.0
     # via sphinx
+beautifulsoup4==4.14.2
+    # via sphinx-toolbox
+cachecontrol==0.14.3
+    # via sphinx-toolbox
 certifi==2025.7.14
     # via
     #   httpcore
     #   httpx
     #   requests
     #   sentry-sdk
+    #   sphinx-prompt
 charset-normalizer==3.4.2
     # via requests
 click==8.2.1
@@ -42,6 +53,10 @@ colorama==0.4.6
     #   uvicorn
 coverage==7.9.2
     # via pytest-cov
+cssutils==2.11.1
+    # via dict2css
+dict2css==0.3.0.post1
+    # via sphinx-toolbox
 dnspython==2.7.0
     # via email-validator
 docstring-parser-fork==0.0.12
@@ -50,7 +65,16 @@ docutils==0.21.2
     # via
     #   restructuredtext-lint
     #   sphinx
+    #   sphinx-prompt
     #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinx-toolbox
+domdf-python-tools==3.10.0
+    # via
+    #   apeye
+    #   apeye-core
+    #   dict2css
+    #   sphinx-toolbox
 email-validator==2.2.0
     # via
     #   fastapi
@@ -65,6 +89,10 @@ fastapi-cli==0.0.8
     # via fastapi
 fastapi-cloud-cli==0.1.4
     # via fastapi-cli
+filelock==3.20.0
+    # via
+    #   cachecontrol
+    #   sphinx-toolbox
 flake8==7.3.0
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -82,6 +110,8 @@ h11==0.16.0
     # via
     #   httpcore
     #   uvicorn
+html5lib==1.1
+    # via sphinx-toolbox
 httpcore==1.0.9
     # via httpx
 httptools==0.6.4
@@ -94,9 +124,11 @@ httpx==0.28.1
 idna==3.10
     # via
     #   anyio
+    #   apeye-core
     #   email-validator
     #   httpx
     #   requests
+    #   sphinx-prompt
 ifaddr==0.2.0
     # via zeroconf
 imagesize==1.4.1
@@ -110,22 +142,31 @@ jinja2==3.1.6
     #   fastapi
     #   sphinx
     #   sphinx-autoapi
+    #   sphinx-jinja2-compat
 jsonschema==4.24.1
     # via labthings-fastapi (pyproject.toml)
 jsonschema-specifications==2025.4.1
     # via jsonschema
 markdown-it-py==3.0.0
     # via rich
 markupsafe==3.0.2
-    # via jinja2
+    # via
+    #   jinja2
+    #   sphinx-jinja2-compat
 mccabe==0.7.0
     # via flake8
 mdurl==0.1.2
     # via markdown-it-py
+more-itertools==10.8.0
+    # via cssutils
+msgpack==1.1.2
+    # via cachecontrol
 mypy==1.17.0
     # via labthings-fastapi (pyproject.toml)
 mypy-extensions==1.1.0
     # via mypy
+natsort==8.4.0
+    # via domdf-python-tools
 numpy==2.2.6
     # via labthings-fastapi (pyproject.toml)
 orjson==3.11.0
@@ -138,6 +179,8 @@ pathspec==0.12.1
     # via mypy
 pillow==11.3.0
     # via labthings-fastapi (pyproject.toml)
+platformdirs==4.5.0
+    # via apeye
 pluggy==1.6.0
     # via
     #   pytest
@@ -167,6 +210,8 @@ pygments==2.19.2
     #   pytest
     #   rich
     #   sphinx
+    #   sphinx-prompt
+    #   sphinx-tabs
 pytest==8.4.1
     # via
     #   labthings-fastapi (pyproject.toml)
@@ -193,7 +238,10 @@ referencing==0.36.2
     #   jsonschema-specifications
     #   types-jsonschema
 requests==2.32.4
-    # via sphinx
+    # via
+    #   apeye
+    #   cachecontrol
+    #   sphinx
 restructuredtext-lint==1.4.0
     # via flake8-rst-docstrings
 rich==14.0.0
@@ -210,26 +258,49 @@ rpds-py==0.26.0
     # via
     #   jsonschema
     #   referencing
+ruamel-yaml==0.18.16
+    # via sphinx-toolbox
+ruamel-yaml-clib==0.2.14
+    # via ruamel-yaml
 ruff==0.12.3
     # via labthings-fastapi (pyproject.toml)
 sentry-sdk==2.33.0
     # via fastapi-cloud-cli
 shellingham==1.5.4
     # via typer
+six==1.17.0
+    # via html5lib
 sniffio==1.3.1
     # via anyio
 snowballstemmer==3.0.1
     # via sphinx
+soupsieve==2.8
+    # via beautifulsoup4
 sphinx==8.1.3
     # via
     #   labthings-fastapi (pyproject.toml)
+    #   autodocsumm
     #   sphinx-autoapi
+    #   sphinx-autodoc-typehints
+    #   sphinx-prompt
     #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinx-toolbox
     #   sphinxcontrib-jquery
 sphinx-autoapi==3.6.0
     # via labthings-fastapi (pyproject.toml)
+sphinx-autodoc-typehints==3.0.1
+    # via sphinx-toolbox
+sphinx-jinja2-compat==0.4.1
+    # via sphinx-toolbox
+sphinx-prompt==1.9.0
+    # via sphinx-toolbox
 sphinx-rtd-theme==3.0.2
     # via labthings-fastapi (pyproject.toml)
+sphinx-tabs==3.4.5
+    # via sphinx-toolbox
+sphinx-toolbox==4.0.0
+    # via labthings-fastapi (pyproject.toml)
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0
@@ -246,6 +317,8 @@ sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 starlette==0.47.1
     # via fastapi
+tabulate==0.9.0
+    # via sphinx-toolbox
 tomli==2.2.1
     # via
     #   coverage
@@ -265,6 +338,8 @@ typing-extensions==4.14.1
     #   labthings-fastapi (pyproject.toml)
     #   anyio
     #   astroid
+    #   beautifulsoup4
+    #   domdf-python-tools
     #   exceptiongroup
     #   fastapi
     #   mypy
@@ -274,6 +349,7 @@ typing-extensions==4.14.1
     #   referencing
     #   rich
     #   rich-toolkit
+    #   sphinx-toolbox
     #   starlette
     #   typer
     #   typing-inspection
@@ -286,13 +362,16 @@ urllib3==2.5.0
     # via
     #   requests
     #   sentry-sdk
+    #   sphinx-prompt
 uvicorn==0.35.0
     # via
     #   fastapi
     #   fastapi-cli
     #   fastapi-cloud-cli
 watchfiles==1.1.0
     # via uvicorn
+webencodings==0.5.1
+    # via html5lib
 websockets==15.0.1
     # via uvicorn
 zeroconf==0.147.0

docs/source/conf.py

@@ -23,6 +23,7 @@
     # "autodoc2",
     "autoapi.extension",
     "sphinx_rtd_theme",
+    "sphinx_toolbox.decorators",
 ]
 
 templates_path = ["_templates"]

pyproject.toml

@@ -40,6 +40,7 @@ dev = [
   "sphinx-rtd-theme",
   "sphinx>=7.2",
   "sphinx-autoapi",
+  "sphinx-toolbox",
   "codespell",
 ]