Use sphinx-autoapi to generate api reference

docs-requirements.txt

@@ -3,3 +3,4 @@ pydata-sphinx-theme>=0.3.1
 Sphinx>=2.0.1,<4.0.0
 nbconvert>=5.5.0
 nbsphinx>=0.8.5
+sphinx-autoapi

docs/source/_auto_api_templates/python/attribute.rst

@@ -0,0 +1,9 @@
+{% if obj.display %}
+{% if obj.docstring|length > 0 %}
+* - {{ obj.name }}
+  - {{ obj.docstring.replace("\n", "") }}
+{% else %}
+* - {{ obj.name }}
+  - {{ obj.value|string }}
+{% endif %}
+{% endif %}

docs/source/_auto_api_templates/python/class.rst

@@ -0,0 +1,77 @@
+{% if obj.display %}
+.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
+{% for (args, return_annotation) in obj.overloads %}
+   {{ " " * (obj.type | length) }}   {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
+{% endfor %}
+
+
+   {% if obj.bases %}
+   {% if "show-inheritance" in autoapi_options %}
+   Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
+   {% endif %}
+
+
+   {% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
+   .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
+      :parts: 1
+      {% if "private-members" in autoapi_options %}
+      :private-bases:
+      {% endif %}
+
+   {% endif %}
+   {% endif %}
+   {% if obj.docstring %}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
+   {% endif %}
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_classes = obj.classes|selectattr("display")|rejectattr("name", "equalto", "args")|list %}
+   {% else %}
+   {% set visible_classes = obj.classes|rejectattr("inherited")|rejectattr("name", "equalto", "args")|selectattr("display")|list %}
+   {% endif %}
+   {% for klass in visible_classes %}
+   {{ klass.render()|indent(3) }}
+   {% endfor %}
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_attributes = obj.attributes|selectattr("display")|list %}
+   {% else %}
+   {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+
+   {% if visible_attributes|length %}
+   **Attributes**
+
+   .. list-table::
+      :widths: 15 85
+      :header-rows: 0
+
+   {% for attribute in visible_attributes|sort(attribute='name') %}
+      * - **{{ attribute.name }}**
+   {% if attribute.docstring|length > 0 %}
+        - {{ attribute.docstring.replace("\n", "") }}
+   {% else %}
+        - {{ attribute.value|string }}
+   {% endif %}
+   {% endfor %}
+   {% endif %}
+
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_methods = obj.methods|selectattr("display")|rejectattr("name", "equalto", "with_traceback")|list %}
+   {% else %}
+   {% set visible_methods = obj.methods|rejectattr("inherited")|rejectattr("name", "equalto", "with_traceback")|selectattr("display")|list %}
+   {% endif %}
+
+   {% if visible_methods|length %}
+   **Methods**
+
+   .. autoapisummary::
+      :nosignatures:
+
+   {% for method in visible_methods|sort(attribute='name') %}
+      {{ obj.obj["full_name"] }}.{{ method.name }}
+   {% endfor %}
+
+   {% for method in visible_methods|sort(attribute='name') %}
+   {{ method.render()|indent(3) }}
+   {% endfor %}
+   {% endif %}
+{% endif %}

docs/source/_auto_api_templates/python/module.rst

@@ -0,0 +1,139 @@
+{% if not obj.display %}
+:orphan:
+
+{% endif %}
+{% if obj.name.split('.')[-1][0] == '_' %}
+{{ obj.name }}
+{% elif obj.name.split('.')|length <= 2 %}
+{{ (' '.join(obj.name.split('.')[-1].split('_'))|title) }}
+{% else %}
+{{ obj.name.split('.')[-1] }}
+{% endif %}
+=========={{ "=" * obj.name|length }}
+
+.. py:module:: {{ obj.name }}
+
+{% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|prepare_docstring|indent(3) }}
+
+{% endif %}
+
+{% block subpackages %}
+{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+{% if visible_subpackages %}
+Subpackages
+-----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 3
+
+{% for subpackage in visible_subpackages %}
+   {{ subpackage.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block submodules %}
+{% set visible_submodules = obj.submodules|selectattr("display")|list %}
+{% if visible_submodules %}
+Submodules
+----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+{% for submodule in visible_submodules %}
+   {{ submodule.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block content %}
+{% if obj.all is not none %}
+{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
+{% elif obj.type is equalto("package") %}
+{% set visible_children = obj.children|selectattr("display")|list %}
+{% else %}
+{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
+{% endif %}
+{% if visible_children %}
+{{ obj.type|title }} Contents
+{{ "-" * obj.type|length }}---------
+
+{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list|sort(attribute="id") %}
+{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list|sort(attribute="id") %}
+{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list|sort(attribute="id") %}
+{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list|sort(attribute="id") %}
+{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+{% block classes scoped %}
+{% if visible_classes %}
+Classes Summary
+~~~~~~~~~~~~~~~
+
+.. autoapisummary::
+
+{% for klass in visible_classes %}
+   {{ klass.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block exceptions scoped %}
+{% if visible_exceptions %}
+Exceptions Summary
+~~~~~~~~~~~~~~~~~~
+
+.. autoapisummary::
+
+{% for klass in visible_exceptions %}
+   `{{ klass.id }}`
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+   :nosignatures:
+
+{% for function in visible_functions %}
+   {{ function.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block attributes scoped %}
+{% if visible_attributes %}
+Attributes Summary
+~~~~~~~~~~~~~~~~~~~
+
+.. autoapisummary::
+
+{% for attribute in visible_attributes %}
+   {{ attribute.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% endif %}
+Contents
+~~~~~~~~~~~~~~~~~~~
+{% for obj_item in visible_children|sort(attribute="id") %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+{% endblock %}

docs/source/_static/style.css

@@ -59,4 +59,18 @@ div.graphviz {
     border-top: 2px solid white;
     margin-left: 7px;
     margin-right: 15px;
+}
+
+.class > dt, .function > dt, .method > dt, .exception > dt {
+  padding: 0.5rem;
+  background-color: #f8f8f8;
+  font-weight: normal;
+  border: 1px solid rgba(0, 0, 0, 0.125);
+  border-left: 2px solid #ff9c34;
+  overflow: auto;
+  margin-bottom: 1rem;
+}
+
+.class > dt::after, .function > dt::after, .method > dt::after {
+  overflow: auto;
 }