Update to copier template 2.3.0 (#580)

* Update to copier template 2.3.0

* Make docs work again, in non-nitpicky mode

* Fix ruff errors

* Fix end of lines

* Support A | B as well as Union[A, B]

* Fix remaining tests

* Fix pyright issues

Fixes #346

* Fix tests on python 3.10

* Review comments

* Fix coverage

* Fix ruff on sytem tests

.copier-answers.yml

@@ -1,9 +1,8 @@
 # Changes here will be overwritten by Copier
-_commit: 2.1.0
+_commit: 2.3.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: tom.cobb@diamond.ac.uk
 author_name: Tom Cobb
-component_owner: ''
 description: Asynchronous Bluesky hardware abstraction code, compatible with control
  systems like EPICS and Tango
 distribution_name: ophyd-async

.devcontainer/devcontainer.json

@@ -52,4 +52,4 @@
  "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
  // After the container is created, install the python project in editable form
  "postCreateCommand": "pip install $([ -f dev-requirements.txt ] && echo '-c dev-requirements.txt') -e '.[dev]' && pre-commit install"
-}
+}

.git-blame-ignore-revs

@@ -7,4 +7,4 @@
 # Use isort to sort imports
 881a35b43584103ca572b6f4e472dd8b6fd6ea87
 # Replace flake8 and mypy with ruff and pyrite
-e2f8317e7584e4de788c2b39e5b5edaa98c1bc9e
+e2f8317e7584e4de788c2b39e5b5edaa98c1bc9e

.github/CONTRIBUTING.md

@@ -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/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: The template to use for reporting bugs and usability issues
+title: " "
+labels: 'bug'
+assignees: ''
+
+---
+
+Describe the bug, including a clear and concise description of the expected behavior, the actual behavior and the context in which you encountered it (ideally include details of your environment).
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,13 @@
+---
+name: Issue
+about: The standard template to use for feature requests, design discussions and tasks
+title: " "
+labels: ''
+assignees: ''
+
+---
+
+A brief description of the issue, including specific stakeholders and the business case where appropriate
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,8 @@
+Fixes #ISSUE
+
+### Instructions to reviewer on how to test:
+1. Do thing x
+2. Confirm thing y happens
+
+### Checks for reviewer
+- [ ] Would the PR title make sense to a user on a set of release notes

.github/pages/index.html

@@ -8,4 +8,4 @@
  <link rel="canonical" href="main/index.html">
 </head>
 
-</html>
+</html>

.github/pages/make_switcher.py

@@ -1,30 +1,32 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
 import json
 import logging
 from argparse import ArgumentParser
 from pathlib import Path
 from subprocess import CalledProcessError, check_output
-from typing import List, Optional
 
 
-def report_output(stdout: bytes, label: str) -> List[str]:
+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
 
 
-def get_branch_contents(ref: str) -> List[str]:
+def get_branch_contents(ref: str) -> list[str]:
  """Get the list of directories in a branch."""
  stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref])
  return report_output(stdout, "Branch contents")
 
 
-def get_sorted_tags_list() -> List[str]:
+def get_sorted_tags_list() -> list[str]:
  """Get a list of sorted tags in descending order from the repository."""
  stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"])
  return report_output(stdout, "Tags list")
 
 
-def get_versions(ref: str, add: Optional[str]) -> List[str]:
+def get_versions(ref: str, add: str | None) -> list[str]:
  """Generate the file containing the list of all GitHub Pages builds."""
  # Get the directories (i.e. builds) from the GitHub Pages branch
  try:
@@ -41,7 +43,7 @@ def get_versions(ref: str, add: Optional[str]) -> List[str]:
  tags = get_sorted_tags_list()
 
  # Make the sorted versions list from main branches and tags
- versions: List[str] = []
+ versions: list[str] = []
  for version in ["master", "main"] + tags:
  if version in builds:
  versions.append(version)
@@ -53,21 +55,20 @@ def get_versions(ref: str, add: Optional[str]) -> 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"
  )

.github/workflows/_docs.yml

@@ -51,4 +51,4 @@ jobs:
  with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  publish_dir: .github/pages
- keep_files: true
+ keep_files: true

.github/workflows/ci.yml

@@ -43,14 +43,14 @@ jobs:
  needs: check
  if: needs.check.outputs.branch-pr == ''
  uses: ./.github/workflows/_dist.yml
- 
+
  pypi:
  if: github.ref_type == 'tag'
  needs: dist
  uses: ./.github/workflows/_pypi.yml
  permissions:
  id-token: write
- 
+
  release:
  if: github.ref_type == 'tag'
  needs: [dist, docs]

.gitignore

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

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
  - id: check-added-large-files
  - id: check-yaml
  - id: check-merge-conflict
+ - id: end-of-file-fixer
 
  - repo: local
  hooks:

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

docs/_templates/custom-module-template.rst

@@ -1,72 +1,42 @@
 .. note::
 
- Ophyd async is included on a provisional basis until the v1.0 release and 
+ Ophyd async is considered experimental until the v1.0 release and
  may change API on minor release numbers before then
 
-{{ fullname | escape | underline}}
+{{ ('``' + fullname + '``') | 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 }}
+{%- set filtered_members = [] %}
+{%- for item in members %}
+ {%- if item in functions + classes + exceptions + attributes %}
+ {% set _ = filtered_members.append(item) %}
+ {%- endif %}
 {%- endfor %}
-{% endif %}
-{% endblock %}
+
+.. 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 %}