Merge pull request #48 from DiamondLightSource/copier-update

Update to copier template 2.3.0

.copier-answers.yml

@@ -1,16 +1,18 @@
 # Changes here will be overwritten by Copier
-_commit: 2.1.0-40-g9e70b8b
+_commit: 2.3.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: [email protected]
 author_name: Gary Yendell
+component_lifecycle: experimental
 component_owner: user:mef65357
+component_type: service
 description: Eiger control system integration with FastCS
-distribution_name: eiger-fastcs
+distribution_name: fastcs-eiger
 docker: true
 docs_type: sphinx
 git_platform: github.com
 github_org: DiamondLightSource
-package_name: eiger_fastcs
+package_name: fastcs_eiger
 pypi: true
-repo_name: eiger-fastcs
+repo_name: fastcs-eiger
 type_checker: mypy

.github/CONTRIBUTING.md

@@ -1,14 +1,14 @@
 # Contribute to the project
 
 Contributions and issues are most welcome! All issues and pull requests are
-handled through [GitHub](https://github.com/DiamondLightSource/eiger-fastcs/issues). Also, please check for any existing issues before
+handled through [GitHub](https://github.com/DiamondLightSource/fastcs-eiger/issues). Also, please check for any existing issues before
 filing a new one. If you have a great idea but it involves big changes, please
 file a ticket before making a pull request! We want to make sure you don't spend
 your time coding something that might not fit the scope of the project.
 
 ## Issue or Discussion?
 
-Github also offers [discussions](https://github.com/DiamondLightSource/eiger-fastcs/discussions) as a place to ask questions and share ideas. If
+Github also offers [discussions](https://github.com/DiamondLightSource/fastcs-eiger/discussions) as a place to ask questions and share ideas. If
 your issue is open ended and it is not obvious when it can be "closed", please
 raise it as a discussion instead.
 
@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.1.0/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.3.0/how-to.html).

.github/pages/make_switcher.py

@@ -1,3 +1,5 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
 import json
 import logging
 from argparse import ArgumentParser
@@ -6,6 +8,7 @@
 
 
 def report_output(stdout: bytes, label: str) -> list[str]:
+    """Print and return something received frm stdout."""
     ret = stdout.decode().strip().split("\n")
     print(f"{label}: {ret}")
     return ret
@@ -52,21 +55,20 @@ def get_versions(ref: str, add: str | None) -> list[str]:
     return versions
 
 
-def write_json(path: Path, repository: str, versions: str):
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
     org, repo_name = repository.split("/")
-    pages_url = f"https://{org}.github.io"
-    if repo_name != f"{org}.github.io":
-        # Only add the repo name if it isn't the source for the org pages site
-        pages_url += f"/{repo_name}"
     struct = [
-        {"version": version, "url": f"{pages_url}/{version}/"} for version in versions
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
     ]
     text = json.dumps(struct, indent=2)
     print(f"JSON switcher:\n{text}")
     path.write_text(text, encoding="utf-8")
 
 
 def main(args=None):
+    """Parse args and write switcher."""
     parser = ArgumentParser(
         description="Make a versions.json file from gh-pages directories"
     )

.gitignore

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

.vscode/launch.json

@@ -8,7 +8,7 @@
             "name": "Eiger IOC",
             "type": "debugpy",
             "request": "launch",
-            "module": "eiger_fastcs",
+            "module": "fastcs_eiger",
             "justMyCode": false,
             "console": "integratedTerminal",
             "args": ["ioc", "EIGER"]
@@ -17,7 +17,7 @@
             "name": "Eiger Asyncio",
             "type": "debugpy",
             "request": "launch",
-            "module": "eiger_fastcs",
+            "module": "fastcs_eiger",
             "justMyCode": false,
             "console": "integratedTerminal",
             "args": ["asyncio"]

Dockerfile

@@ -30,5 +30,5 @@ RUN mkdir -p /epics/opi
 WORKDIR /epics/opi
 
 # change this entrypoint if it is not the same as the repo
-ENTRYPOINT ["eiger-fastcs"]
+ENTRYPOINT ["fastcs-eiger"]
 CMD ["--version"]

README.md

@@ -1,9 +1,9 @@
-[![CI](https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/DiamondLightSource/eiger-fastcs/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/eiger-fastcs)
-[![PyPI](https://img.shields.io/pypi/v/eiger-fastcs.svg)](https://pypi.org/project/eiger-fastcs)
+[![CI](https://github.com/DiamondLightSource/fastcs-eiger/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/fastcs-eiger/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/DiamondLightSource/fastcs-eiger/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/fastcs-eiger)
+[![PyPI](https://img.shields.io/pypi/v/fastcs-eiger.svg)](https://pypi.org/project/fastcs-eiger)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# Eiger FastCS
+# FastCS Eiger
 
 Control system integration for Dectris Eiger detectors using FastCS.
 
@@ -15,22 +15,21 @@ Control system integration for Dectris Eiger detectors using FastCS.
 
 2. Run the IOC against the simulated detector, either from a local checkout
 
-    i. `eiger-fastcs ioc EIGER` (or run `Eiger IOC` vscode launch config)
+    i. `fastcs-eiger ioc EIGER` (or run `Eiger IOC` vscode launch config)
 
 3. or the container
 
     i. Make a local directory for UIs `mkdir /tmp/opi`
 
-    ii. `podman run --rm -it -v /tmp/opi:/epics/opi --net=host ghcr.io/DiamondLightSource/eiger-fastcs:latest`
+    ii. `podman run --rm -it -v /tmp/opi:/epics/opi --net=host ghcr.io/DiamondLightSource/fastcs-eiger:latest`
 
-Source          | <https://github.com/DiamondLightSource/eiger-fastcs>
+Source          | <https://github.com/DiamondLightSource/fastcs-eiger>
 :---:           | :---:
-PyPI            | `pip install eiger-fastcs`
-Docker          | `docker run ghcr.io/diamondlightsource/eiger-fastcs:latest`
-Documentation   | <https://diamondlightsource.github.io/eiger-fastcs>
-Releases        | <https://github.com/DiamondLightSource/eiger-fastcs/releases>
-
+PyPI            | `pip install fastcs-eiger`
+Docker          | `docker run ghcr.io/diamondlightsource/fastcs-eiger:latest`
+Documentation   | <https://diamondlightsource.github.io/fastcs-eiger>
+Releases        | <https://github.com/DiamondLightSource/fastcs-eiger/releases>
 
 <!-- README only content. Anything below this line won't be included in index.md -->
 
-See https://diamondlightsource.github.io/eiger-fastcs for more detailed documentation.
+See https://diamondlightsource.github.io/fastcs-eiger for more detailed documentation.

catalog-info.yaml

@@ -1,10 +1,10 @@
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
-  name: eiger-fastcs
-  title: eiger-fastcs
+  name: fastcs-eiger
+  title: fastcs-eiger
   description: Eiger control system integration with FastCS
 spec:
-  type: documentation
+  type: service
   lifecycle: experimental
   owner: user:mef65357

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 fastcs_eiger and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    fastcs_eiger

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

@@ -1,24 +1,25 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 
 import sys
 from pathlib import Path
 from subprocess import check_output
 
 import requests
 
-import eiger_fastcs
+import fastcs_eiger
 
 # -- General configuration ------------------------------------------------
 
 # General information about the project.
-project = "eiger-fastcs"
+project = "fastcs-eiger"
 
 # The full version, including alpha/beta/rc tags.
-release = eiger_fastcs.__version__
+release = fastcs_eiger.__version__
 
 # The short X.Y version.
 if "+" in release:
@@ -32,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
@@ -80,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"
 
@@ -119,7 +128,7 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
-github_repo = "eiger-fastcs"
+github_repo = "fastcs-eiger"
 github_user = "DiamondLightSource"
 switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
 switcher_exists = requests.get(switcher_json).ok

docs/how-to/run-container.md

@@ -1,14 +1,14 @@
 # Run in a container
 
-Pre-built containers with eiger-fastcs and its dependencies already
-installed are available on [Github Container Registry](https://ghcr.io/DiamondLightSource/eiger-fastcs).
+Pre-built containers with fastcs-eiger and its dependencies already
+installed are available on [Github Container Registry](https://ghcr.io/DiamondLightSource/fastcs-eiger).
 
 ## Starting the container
 
 To pull the container from github container registry and run:
 
 ```
-$ docker run ghcr.io/diamondlightsource/eiger-fastcs:latest --version
+$ docker run ghcr.io/diamondlightsource/fastcs-eiger:latest --version
 ```
 
 To get a released version, use a numbered release instead of `latest`.

docs/reference.md

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