use autosummary to generate most of the API Reference

- custom _template/autosummary/module.rst to include docs
  for all module :members" (shows up directly after the summary
  tables)
- module docs should *not* contain autodocs for members, only general
  descriptions and examples
- all files inside api/ are autogenerated whenever sphinx is run
  (no need to add to the repository, hence excluded in .gitignore)

.gitignore

@@ -5,3 +5,10 @@
 *.egg-info
 # Visual studio code
 .vscode
+
+# editor files
+*~
+
+# generated files
+docs/build
+docs/source/api/*.rst

docs/source/_templates/autosummary/module.rst

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

docs/source/conf.py

@@ -38,6 +38,7 @@ release = '3.2.0'
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
               'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
               'sphinx.ext.napoleon', 'sphinx.ext.todo',
+              'sphinx.ext.autosummary',
 ##              'sphinx_sitemap',
               'sphinx_rtd_theme']
 
@@ -55,6 +56,11 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
+# We use a customized _templates/autosummary/module.rst to document members, too.
+autosummary_generate = True
+autosummary_imported_members = False
+autosummary_generate_overwrite = True
 
 # -- Options for HTML output -------------------------------------------------