Skip to content

Commit ab6b0c6

Browse files
rwb27rwb27
authored
Merge pull request #307 from labthings/summary_api_docs
Summary API Docs
2 parents 5d15e9a + 079566f commit ab6b0c6

56 files changed

Lines changed: 1368 additions & 422 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Documentation
2+
3+
on:
4+
- pull_request
5+
6+
jobs:
7+
build-docs:
8+
runs-on: ubuntu-latest
9+
10+
steps:
11+
- uses: actions/checkout@v3
12+
13+
- name: Set up Python
14+
uses: actions/setup-python@v4
15+
with:
16+
python-version: "3.11"
17+
18+
- name: Install Dependencies
19+
run: pip install -e . -r dev-requirements.txt
20+
21+
- name: Print installed packages
22+
run: pip freeze
23+
24+
- name: Build docs with Sphinx
25+
working-directory: ./docs/
26+
run: make html
27+
28+
- name: Check public API docs are complete
29+
working-directory: ./docs/
30+
run: python check_public_api.py

‎dev-requirements.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ attrs==25.3.0
2222
# via
2323
# jsonschema
2424
# referencing
25+
# sphobjinv
2526
autodocsumm==0.2.14
2627
# via sphinx-toolbox
2728
babel==2.17.0
@@ -37,6 +38,7 @@ certifi==2025.7.14
3738
# requests
3839
# sentry-sdk
3940
# sphinx-prompt
41+
# sphobjinv
4042
charset-normalizer==3.4.2
4143
# via requests
4244
click==8.2.1
@@ -140,7 +142,9 @@ jinja2==3.1.6
140142
# sphinx-autoapi
141143
# sphinx-jinja2-compat
142144
jsonschema==4.24.1
143-
# via labthings-fastapi (pyproject.toml)
145+
# via
146+
# labthings-fastapi (pyproject.toml)
147+
# sphobjinv
144148
jsonschema-specifications==2025.4.1
145149
# via jsonschema
146150
markdown-it-py==3.0.0
@@ -309,6 +313,8 @@ sphinxcontrib-qthelp==2.0.0
309313
# via sphinx
310314
sphinxcontrib-serializinghtml==2.0.0
311315
# via sphinx
316+
sphobjinv==2.4
317+
# via labthings-fastapi (pyproject.toml)
312318
starlette==0.47.1
313319
# via fastapi
314320
tabulate==0.9.0

‎docs/autoapi_templates/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Internal API Reference
2+
======================
3+
4+
This page contains auto-generated API reference documentation [#f1]_. Most users should find the :ref:`public_api` more useful.
5+
6+
.. toctree::
7+
:titlesonly:
8+
9+
{% for page in pages|selectattr("is_top_level_object") %}
10+
{{ page.include_path }}
11+
{% endfor %}
12+
13+
.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

‎docs/autoapi_templates/python/attribute.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% extends "python/data.rst" %}

‎docs/autoapi_templates/python/class.rst‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
{% if obj.display %}
2+
{% if is_own_page %}
3+
{{ obj.id }}
4+
{{ "=" * obj.id | length }}
5+
6+
{% endif %}
7+
{% set visible_children = obj.children|selectattr("display")|list %}
8+
{% set own_page_children = visible_children|selectattr("type", "in", own_page_types)|list %}
9+
{% if is_own_page and own_page_children %}
10+
.. toctree::
11+
:hidden:
12+
13+
{% for child in own_page_children %}
14+
{{ child.include_path }}
15+
{% endfor %}
16+
17+
{% endif %}
18+
.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}{% if obj.args %}({{ obj.args }}){% endif %}
19+
20+
{% for (args, return_annotation) in obj.overloads %}
21+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
22+
23+
{% endfor %}
24+
{% if obj.bases %}
25+
{% if "show-inheritance" in autoapi_options %}
26+
27+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
28+
{% endif %}
29+
30+
31+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
32+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
33+
:parts: 1
34+
{% if "private-members" in autoapi_options %}
35+
:private-bases:
36+
{% endif %}
37+
38+
{% endif %}
39+
{% endif %}
40+
{% if obj.docstring %}
41+
42+
{{ obj.docstring|indent(3) }}
43+
{% endif %}
44+
{% for obj_item in visible_children %}
45+
{% if obj_item.type not in own_page_types %}
46+
47+
{{ obj_item.render()|indent(3) }}
48+
{% endif %}
49+
{% endfor %}
50+
{% if is_own_page and own_page_children %}
51+
{% set visible_attributes = own_page_children|selectattr("type", "equalto", "attribute")|list %}
52+
{% if visible_attributes %}
53+
Attributes
54+
----------
55+
56+
.. autoapisummary::
57+
58+
{% for attribute in visible_attributes %}
59+
{{ attribute.id }}
60+
{% endfor %}
61+
62+
63+
{% endif %}
64+
{% set visible_exceptions = own_page_children|selectattr("type", "equalto", "exception")|list %}
65+
{% if visible_exceptions %}
66+
Exceptions
67+
----------
68+
69+
.. autoapisummary::
70+
71+
{% for exception in visible_exceptions %}
72+
{{ exception.id }}
73+
{% endfor %}
74+
75+
76+
{% endif %}
77+
{% set visible_classes = own_page_children|selectattr("type", "equalto", "class")|list %}
78+
{% if visible_classes %}
79+
Classes
80+
-------
81+
82+
.. autoapisummary::
83+
84+
{% for klass in visible_classes %}
85+
{{ klass.id }}
86+
{% endfor %}
87+
88+
89+
{% endif %}
90+
{% set visible_methods = own_page_children|selectattr("type", "equalto", "method")|list %}
91+
{% if visible_methods %}
92+
Methods
93+
-------
94+
95+
.. autoapisummary::
96+
97+
{% for method in visible_methods %}
98+
{{ method.id }}
99+
{% endfor %}
100+
101+
102+
{% endif %}
103+
{% endif %}
104+
{% endif %}

‎docs/autoapi_templates/python/data.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{% if obj.display %}
2+
{% if is_own_page %}
3+
{{ obj.id }}
4+
{{ "=" * obj.id | length }}
5+
6+
{% endif %}
7+
.. py:{% if obj.is_type_alias() %}type{% else %}{{ obj.type }}{% endif %}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.name }}{% endif %}
8+
{% if obj.is_type_alias() %}
9+
{% if obj.value %}
10+
11+
:canonical: {{ obj.value }}
12+
{% endif %}
13+
{% else %}
14+
{% if obj.annotation is not none %}
15+
16+
:type: {% if obj.annotation %} {{ obj.annotation }}{% endif %}
17+
{% endif %}
18+
{% if obj.value is not none %}
19+
20+
{% if obj.value.splitlines()|count > 1 %}
21+
:value: Multiline-String
22+
23+
.. raw:: html
24+
25+
<details><summary>Show Value</summary>
26+
27+
.. code-block:: python
28+
29+
{{ obj.value|indent(width=6,blank=true) }}
30+
31+
.. raw:: html
32+
33+
</details>
34+
35+
{% else %}
36+
:value: {{ obj.value|truncate(100) }}
37+
{% endif %}
38+
{% endif %}
39+
{% endif %}
40+
41+
{% if obj.docstring %}
42+
43+
{{ obj.docstring|indent(3) }}
44+
{% endif %}
45+
{% endif %}

‎docs/autoapi_templates/python/exception.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% extends "python/class.rst" %}

‎docs/autoapi_templates/python/function.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{% if obj.display %}
2+
{% if is_own_page %}
3+
{{ obj.id }}
4+
{{ "=" * obj.id | length }}
5+
6+
{% endif %}
7+
.. 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 %}
8+
{% for (args, return_annotation) in obj.overloads %}
9+
10+
{%+ if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
11+
{% endfor %}
12+
{% for property in obj.properties %}
13+
14+
:{{ property }}:
15+
{% endfor %}
16+
17+
{% if obj.docstring %}
18+
19+
{{ obj.docstring|indent(3) }}
20+
{% endif %}
21+
{% endif %}

‎docs/autoapi_templates/python/method.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{% if obj.display %}
2+
{% if is_own_page %}
3+
{{ obj.id }}
4+
{{ "=" * obj.id | length }}
5+
6+
{% endif %}
7+
.. 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 %}
8+
{% for (args, return_annotation) in obj.overloads %}
9+
10+
{%+ if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
11+
{% endfor %}
12+
{% for property in obj.properties %}
13+
14+
:{{ property }}:
15+
{% endfor %}
16+
17+
{% if obj.docstring %}
18+
19+
{{ obj.docstring|indent(3) }}
20+
{% endif %}
21+
{% endif %}

0 commit comments

Comments
 (0)