WIP autosummary

docs/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% 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/custom-module-template.rst

@@ -0,0 +1,67 @@
+{{ 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:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/conf.py

@@ -32,6 +32,7 @@
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -101,6 +102,16 @@
 # full-qualified object name.
 autodoc_type_aliases = dict(AxesPoints="scanspec.core.AxesPoints")
 
+# If False and a module has the __all__ attribute set, autosummary documents
+# every member listed in __all__ and no others. Default is True
+autosummary_ignore_module_all = False
+
+# Turn on sphinx.ext.autosummary
+autosummary_generate = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
 # Include source in plot directive by default
 plot_include_source = True
 
@@ -117,7 +128,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # These patterns also affect html_static_path and html_extra_path
-exclude_patterns = ["_build"]
+exclude_patterns = ["build/html"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

docs/reference/api.rst

@@ -1,60 +1,9 @@
 API
 ===
 
-.. automodule:: scanspec
+.. autosummary::
+   :toctree: ../build/autosummary
+   :template: custom-module-template.rst
+   :recursive:
 
-    ``scanspec``
-    ------------
-
-
-The top level scanspec module contains a number of packages that can be used
-from code:
-
-- `scanspec.core`: Core classes like `Frames` and `Path`
-- `scanspec.specs`: `Spec` and its subclasses
-- `scanspec.regions`: `Region` and its subclasses
-- `scanspec.plot`: `plot_spec` to visualize a scan
-- `scanspec.service`: Defines queries and field structure in REST such as `MidpointsResponse`
-
-.. data:: scanspec.__version__
-    :type: str
-
-    Version number as calculated by https://github.com/dls-controls/versiongit
-
-.. automodule:: scanspec.core
-    :members:
-
-    ``scanspec.core``
-    -----------------
-
-.. automodule:: scanspec.specs
-    :members:
-
-    ``scanspec.specs``
-    ------------------
-
-    .. inheritance-diagram:: scanspec.specs
-        :top-classes: scanspec.specs.Spec
-        :parts: 1
-
-.. automodule:: scanspec.regions
-    :members:
-
-    ``scanspec.regions``
-    --------------------
-
-    .. inheritance-diagram:: scanspec.regions
-        :top-classes: scanspec.regions.Region
-        :parts: 1
-
-.. automodule:: scanspec.plot
-    :members:
-
-    ``scanspec.plot``
-    -----------------
-
-.. automodule:: scanspec.service
-    :members:
-
-    ``scanspec.service``
-    --------------------
+   scanspec

pyproject.toml

@@ -138,5 +138,5 @@ commands =
     pytest: pytest {posargs}
     mypy: mypy src tests {posargs}
     pre-commit: pre-commit run --all-files {posargs}
-    docs: sphinx-{posargs:build -EW --keep-going} -T docs build/html
+    docs: sphinx-{posargs:build -EW --keep-going} -T docs docs/build/html
 """

src/scanspec/__init__.py

@@ -1,6 +1,8 @@
+"""The top level scanspec module"""
 from importlib.metadata import version
 
+#: The version as calculated by setuptools_scm
 __version__ = version("scanspec")
 del version
 
-__all__ = ["__version__", "specs", "regions"]
+__all__ = ["__version__", "core", "specs", "regions", "plot", "service"]