Skip to content

Commit ec4e4d6

Browse files
rwb27rwb27
committed
Rename and complete public API documentation.
This adds in the remaining symbols and renames "quick reference" to "public API". Renaming the full API docs required me to pull in templates for autoapi. This might go away in the future if we transition fully to autodoc. I've had to fix a couple of references too.
1 parent cdc6e38 commit ec4e4d6

File tree

16 files changed

+418
-6
lines changed

16 files changed

+418
-6
lines changed

‎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 %}

‎docs/autoapi_templates/python/module.rst‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
{% if obj.display %}
2+
{% if is_own_page %}
3+
{{ obj.id }}
4+
{{ "=" * obj.id|length }}
5+
6+
.. py:module:: {{ obj.name }}
7+
8+
{% if obj.docstring %}
9+
.. autoapi-nested-parse::
10+
11+
{{ obj.docstring|indent(3) }}
12+
13+
{% endif %}
14+
15+
{% block submodules %}
16+
{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
17+
{% set visible_submodules = obj.submodules|selectattr("display")|list %}
18+
{% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
19+
{% if visible_submodules %}
20+
Submodules
21+
----------
22+
23+
.. toctree::
24+
:maxdepth: 1
25+
26+
{% for submodule in visible_submodules %}
27+
{{ submodule.include_path }}
28+
{% endfor %}
29+
30+
31+
{% endif %}
32+
{% endblock %}
33+
{% block content %}
34+
{% set visible_children = obj.children|selectattr("display")|list %}
35+
{% if visible_children %}
36+
{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
37+
{% if visible_attributes %}
38+
{% if "attribute" in own_page_types or "show-module-summary" in autoapi_options %}
39+
Attributes
40+
----------
41+
42+
{% if "attribute" in own_page_types %}
43+
.. toctree::
44+
:hidden:
45+
46+
{% for attribute in visible_attributes %}
47+
{{ attribute.include_path }}
48+
{% endfor %}
49+
50+
{% endif %}
51+
.. autoapisummary::
52+
53+
{% for attribute in visible_attributes %}
54+
{{ attribute.id }}
55+
{% endfor %}
56+
{% endif %}
57+
58+
59+
{% endif %}
60+
{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %}
61+
{% if visible_exceptions %}
62+
{% if "exception" in own_page_types or "show-module-summary" in autoapi_options %}
63+
Exceptions
64+
----------
65+
66+
{% if "exception" in own_page_types %}
67+
.. toctree::
68+
:hidden:
69+
70+
{% for exception in visible_exceptions %}
71+
{{ exception.include_path }}
72+
{% endfor %}
73+
74+
{% endif %}
75+
.. autoapisummary::
76+
77+
{% for exception in visible_exceptions %}
78+
{{ exception.id }}
79+
{% endfor %}
80+
{% endif %}
81+
82+
83+
{% endif %}
84+
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
85+
{% if visible_classes %}
86+
{% if "class" in own_page_types or "show-module-summary" in autoapi_options %}
87+
Classes
88+
-------
89+
90+
{% if "class" in own_page_types %}
91+
.. toctree::
92+
:hidden:
93+
94+
{% for klass in visible_classes %}
95+
{{ klass.include_path }}
96+
{% endfor %}
97+
98+
{% endif %}
99+
.. autoapisummary::
100+
101+
{% for klass in visible_classes %}
102+
{{ klass.id }}
103+
{% endfor %}
104+
{% endif %}
105+
106+
107+
{% endif %}
108+
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
109+
{% if visible_functions %}
110+
{% if "function" in own_page_types or "show-module-summary" in autoapi_options %}
111+
Functions
112+
---------
113+
114+
{% if "function" in own_page_types %}
115+
.. toctree::
116+
:hidden:
117+
118+
{% for function in visible_functions %}
119+
{{ function.include_path }}
120+
{% endfor %}
121+
122+
{% endif %}
123+
.. autoapisummary::
124+
125+
{% for function in visible_functions %}
126+
{{ function.id }}
127+
{% endfor %}
128+
{% endif %}
129+
130+
131+
{% endif %}
132+
{% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %}
133+
{% if this_page_children %}
134+
{{ obj.type|title }} Contents
135+
{{ "-" * obj.type|length }}---------
136+
137+
{% for obj_item in this_page_children %}
138+
{{ obj_item.render()|indent(0) }}
139+
{% endfor %}
140+
{% endif %}
141+
{% endif %}
142+
{% endblock %}
143+
{% else %}
144+
.. py:module:: {{ obj.name }}
145+
146+
{% if obj.docstring %}
147+
.. autoapi-nested-parse::
148+
149+
{{ obj.docstring|indent(6) }}
150+
151+
{% endif %}
152+
{% for obj_item in visible_children %}
153+
{{ obj_item.render()|indent(3) }}
154+
{% endfor %}
155+
{% endif %}
156+
{% endif %}

‎docs/autoapi_templates/python/package.rst‎

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

‎docs/autoapi_templates/python/property.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:property:: {% if is_own_page %}{{ obj.id}}{% else %}{{ obj.short_name }}{% endif %}
8+
{% if obj.annotation %}
9+
10+
:type: {{ obj.annotation }}
11+
{% endif %}
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)