Add API documentation for the blacs submodules.

Relies on recursive autosummary and a custom template.

In testing builds, noticed that experiment_queue and plugins depended on
a properly set up labconfig; namely experiment_shot_storage. Might be an
issue on readthedocs.

.gitignore

@@ -158,4 +158,5 @@ conda_packages/
 # Sphinx documentation
 docs/html/
 docs/source/_build/
-docs/source/components.rst
+docs/source/components.rst
+docs/source/api/_autosummary

docs/source/_templates/autosummary-class.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/_templates/autosummary-module.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary-class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary-module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/api/index.rst

@@ -0,0 +1,17 @@
+API Reference
+=============
+
+.. autosummary::
+    :toctree: _autosummary
+    :template: autosummary-module.rst
+    :recursive:
+
+    blacs.analysis_submission
+    blacs.compile_and_restart
+    blacs.device_base_class
+    blacs.experiment_queue
+    blacs.front_panel_settings
+    blacs.notifications
+    blacs.output_classes
+    blacs.plugins
+    blacs.tab_base_classes

docs/source/conf.py

@@ -39,6 +39,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
@@ -49,6 +50,7 @@
 ]
 
 autodoc_typehints = 'description'
+autosummary_generate = True
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True

docs/source/index.rst

@@ -6,11 +6,15 @@
 blacs
 =====
 
+A graphical interface to scientific instruments and experiment supervision.
+
 .. toctree::
    :maxdepth: 2
    :hidden:
    :caption: DOCUMENTATION
 
+   api/index
+
 .. toctree::
    :maxdepth: 2
    :hidden:

docs/source/introduction.rst

@@ -0,0 +1,2 @@
+Introduction
+============

setup.cfg

@@ -42,7 +42,7 @@ gui_scripts =
 pyqt = PyQt5
 docs = 
   PyQt5
-  Sphinx==3.0.1
+  Sphinx==3.1.2
   sphinx-rtd-theme==0.4.3
   recommonmark==0.6.0
   m2r==0.2.1