deploy: DiamondLightSource/python-copier-template@de15bec

.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 2.2.0-20-gb0dabb0
+_commit: 2.2.0-23-gde15bec
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: tom.cobb@diamond.ac.uk
 author_name: Tom Cobb

.gitignore

@@ -55,6 +55,7 @@ cov.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_api
 
 # PyBuilder
 target/

docs/_api.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for python_copier_template_example and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    python_copier_template_example

docs/_templates/custom-module-template.rst

@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+    {%- if item in functions + classes + exceptions + attributes %}
+        {% set _ = filtered_members.append(item) %}
+    {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Submodules
+
+    .. autosummary::
+        :toctree:
+        :template: custom-module-template.rst
+        :recursive:
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block members %}
+    {% if filtered_members %}
+    .. rubric:: Members
+
+    .. autosummary::
+        :nosignatures:
+    {% for item in filtered_members %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

docs/conf.py

@@ -33,6 +33,8 @@
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    # and making summary tables at the top of API docs
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -81,6 +83,12 @@
 # Don't inherit docstrings from baseclasses
 autodoc_inherit_docstrings = False
 
+# Document only what is in __all__
+autosummary_ignore_module_all = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # Output graphviz directive produced images in a scalable format
 graphviz_output_format = "svg"
 

docs/reference.md

@@ -6,7 +6,7 @@ Technical reference material including APIs and release notes.
 :maxdepth: 1
 :glob:
 
-reference/*
+API <_api/python_copier_template_example>
 genindex
 Release Notes <https://github.com/DiamondLightSource/python-copier-template-example/releases>
 ```

src/python_copier_template_example/__init__.py

@@ -1,3 +1,11 @@
+"""Top level API.
+
+.. data:: __version__
+    :type: str
+
+    Version number as calculated by https://github.com/pypa/setuptools_scm
+"""
+
 from ._version import __version__
 
 __all__ = ["__version__"]

src/python_copier_template_example/__main__.py

@@ -1,4 +1,5 @@
 """Interface for ``python -m python_copier_template_example``."""
+
 from argparse import ArgumentParser
 from collections.abc import Sequence