Skip to content

Commit 6a3bb3d

Browse files
authored
Update Sphinx autogen to use AutoAPI (#150)
* use imported members; cleaner toctree * remove explicit init doc * remove attributes from template (use docstring) * job docstrings * move module blurb into imported class member * slice: clean up line breaks * add refs * exclude init * exclude wip features * bring annotations back we should parse @Property, not the docstring. as a best practice, any attributes must be exposed via the @Property decorator, and should otherwise be privated using the _ prefix * doc dataset attributes * migrate TODOCs * fix todo directives * fix todo directives 2 * parse typehints from function signature * migrate from autosummary to autoapi * fix autoapi config - no class attributes by default (can override) - use __all__ to expose public members - fix signature and typehint funkiness * lint
1 parent 26df667 commit 6a3bb3d

24 files changed

+382
-204
lines changed

docs/_templates/autosummary/base.rst

Lines changed: 0 additions & 5 deletions
This file was deleted.

docs/_templates/autosummary/class.rst

Lines changed: 0 additions & 9 deletions
This file was deleted.

docs/_templates/autosummary/function.rst

Lines changed: 0 additions & 8 deletions
This file was deleted.

docs/_templates/autosummary/module.rst

Lines changed: 0 additions & 65 deletions
This file was deleted.

docs/_templates/index.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
API Reference
2+
=============
3+
4+
.. toctree::
5+
:titlesonly:
6+
7+
{% for page in pages %}
8+
{% if page.top_level_object and page.display %}
9+
{{ page.include_path }}
10+
{% endif %}
11+
{% endfor %}

docs/_templates/nucleus-module.rst

Lines changed: 0 additions & 64 deletions
This file was deleted.

docs/_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/_templates/python/class.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{% if obj.display %}
2+
.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
3+
{% for (args, return_annotation) in obj.overloads %}
4+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
5+
{% endfor %}
6+
7+
8+
{% if obj.bases %}
9+
{% if "show-inheritance" in autoapi_options %}
10+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
11+
{% endif %}
12+
13+
14+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
15+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
16+
:parts: 1
17+
{% if "private-members" in autoapi_options %}
18+
:private-bases:
19+
{% endif %}
20+
21+
{% endif %}
22+
{% endif %}
23+
24+
{% if obj.docstring %}
25+
{{ obj.docstring|indent(3) }}
26+
{% endif %}
27+
28+
{% if "inherited-members" in autoapi_options %}
29+
{% set visible_classes = obj.classes|selectattr("display")|list %}
30+
{% else %}
31+
{% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
32+
{% endif %}
33+
{% for klass in visible_classes %}
34+
{{ klass.render()|indent(3) }}
35+
{% endfor %}
36+
37+
{% if "inherited-members" in autoapi_options %}
38+
{% set visible_methods = obj.methods|selectattr("display")|list %}
39+
{% else %}
40+
{% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
41+
{% endif %}
42+
{% for method in visible_methods %}
43+
{{ method.render()|indent(3) }}
44+
{% endfor %}
45+
{% endif %}

docs/_templates/python/data.rst

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{% if obj.display %}
2+
.. py:{{ obj.type }}:: {{ obj.name }}
3+
{%+ if obj.value is not none or obj.annotation is not none -%}
4+
:annotation:
5+
{%- if obj.annotation %} :{{ obj.annotation }}
6+
{%- endif %}
7+
{%- if obj.value is not none %} = {%
8+
if obj.value is string and obj.value.splitlines()|count > 1 -%}
9+
Multiline-String
10+
11+
.. raw:: html
12+
13+
<details><summary>Show Value</summary>
14+
15+
.. code-block:: text
16+
:linenos:
17+
18+
{{ obj.value|indent(width=8) }}
19+
20+
.. raw:: html
21+
22+
</details>
23+
24+
{%- else -%}
25+
{{ obj.value|string|truncate(100) }}
26+
{%- endif %}
27+
{%- endif %}
28+
{% endif %}
29+
30+
31+
{{ obj.docstring|indent(3) }}
32+
{% endif %}

docs/_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" %}

0 commit comments

Comments
 (0)