docs(*): set up autosummary

- generates doc files for each source module and classes/functions within recursively

.gitignore

@@ -63,6 +63,7 @@ output/*/index.html
 
 # Sphinx
 docs/_build
+docs/reference/autosummary/
 
 .DS_Store
 *~

docs/_templates/class.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% 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/_templates/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: 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: module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/conf.py

@@ -21,6 +21,8 @@
     'sphinx.ext.viewcode',
     'sphinx_mdinclude',
 ]
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'McSAS3'
@@ -34,7 +36,6 @@
 autodoc_mock_imports = ["ipykernel", "notebook", "pandas", "ipywidgets", "matplotlib", "scipy"]
 
 pygments_style = 'trac'
-templates_path = ['.']
 extlinks = {
     'issue': (join(project_meta['project']['urls']['repository'], 'issues', '%s'), '#%s'),
     'pr': (join(project_meta['project']['urls']['repository'], 'pull', '%s'), 'PR #%s'),

docs/reference/index.rst

@@ -1,7 +1,11 @@
 Reference
 =========
 
-.. toctree::
-    :glob:
+Some words.
 
-    mcsas3*
+.. autosummary::
+   :toctree: autosummary
+   :template: module.rst
+   :recursive:
+
+   mcsas3