From 2e0e5f2fb48131f115b5515ac0ed928dde7b497f Mon Sep 17 00:00:00 2001 From: Zoheb Shaikh Date: Tue, 14 Jan 2025 13:59:16 +0000 Subject: [PATCH] adopt python copier template 2.6.0 --- .copier-answers.yml | 4 ++- .devcontainer/devcontainer.json | 8 ++--- .github/CONTRIBUTING.md | 2 +- .github/pages/make_switcher.py | 14 ++++---- .github/workflows/_pypi.yml | 2 ++ .github/workflows/_release.yml | 2 +- .gitignore | 1 + Dockerfile | 6 ++-- README.md | 3 +- docs/_api.rst | 16 ++++++++++ docs/_templates/custom-module-template.rst | 37 ++++++++++++++++++++++ docs/conf.py | 19 ++++++++--- docs/reference.md | 1 + src/htss_rig_bluesky/__init__.py | 8 +++++ src/htss_rig_bluesky/__main__.py | 16 +++++++--- 15 files changed, 113 insertions(+), 26 deletions(-) create mode 100644 docs/_api.rst create mode 100644 docs/_templates/custom-module-template.rst diff --git a/.copier-answers.yml b/.copier-answers.yml index 5801bb0..a8f1d61 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,9 +1,11 @@ # Changes here will be overwritten by Copier -_commit: 2.2.0 +_commit: 2.6.0 _src_path: gh:DiamondLightSource/python-copier-template author_email: callum.forrester@diamond.ac.uk author_name: Callum Forrester +component_lifecycle: experimental component_owner: group:default/daq +component_type: library description: Bluesky playground environment for Diamond's htss rigs distribution_name: htss-rig-bluesky docker: true diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index d3d639a..979a89c 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -28,11 +28,11 @@ } }, "features": { - // Some default things like git config - "ghcr.io/devcontainers/features/common-utils:2": { - "upgradePackages": false - } + // add in eternal history and other bash features + "ghcr.io/diamondlightsource/devcontainer-features/bash-config:1.0.0": {} }, + // Create the config folder for the bash-config feature + "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/bash-config", "runArgs": [ // Allow the container to access the host X11 display and EPICS CA "--net=host", diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7d7d5b9..6460c3b 100644 --- a/.github/CONTRIBUTING.md +++ b/.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.2.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.6.0/how-to.html). diff --git a/.github/pages/make_switcher.py b/.github/pages/make_switcher.py index 29f646c..c06813a 100755 --- a/.github/pages/make_switcher.py +++ b/.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,14 +55,12 @@ 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}") @@ -67,6 +68,7 @@ def write_json(path: Path, repository: str, versions: str): def main(args=None): + """Parse args and write switcher.""" parser = ArgumentParser( description="Make a versions.json file from gh-pages directories" ) diff --git a/.github/workflows/_pypi.yml b/.github/workflows/_pypi.yml index 0c5258d..8032bba 100644 --- a/.github/workflows/_pypi.yml +++ b/.github/workflows/_pypi.yml @@ -15,3 +15,5 @@ jobs: - name: Publish to PyPI using trusted publishing uses: pypa/gh-action-pypi-publish@release/v1 + with: + attestations: false diff --git a/.github/workflows/_release.yml b/.github/workflows/_release.yml index 10d8ed8..81b6264 100644 --- a/.github/workflows/_release.yml +++ b/.github/workflows/_release.yml @@ -23,7 +23,7 @@ jobs: - name: Create GitHub Release # We pin to the SHA, not the tag, for security reasons. # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions - uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8 + uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9 with: prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }} files: "*" diff --git a/.gitignore b/.gitignore index 2593ec7..0f33bf2 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,7 @@ cov.xml # Sphinx documentation docs/_build/ +docs/_api # PyBuilder target/ diff --git a/Dockerfile b/Dockerfile index 904d999..77fa523 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,7 @@ # The devcontainer should use the developer target and run as root with podman # or docker with user namespaces. ARG PYTHON_VERSION=3.11 -FROM python:${PYTHON_VERSION} as developer +FROM python:${PYTHON_VERSION} AS developer # Add any system dependencies for the developer/build environment here RUN apt-get update && apt-get install -y --no-install-recommends \ @@ -19,13 +19,13 @@ RUN python -m venv /venv ENV PATH=/venv/bin:$PATH # The build stage installs the context into the venv -FROM developer as build +FROM developer AS build COPY . /context WORKDIR /context RUN touch dev-requirements.txt && pip install -c dev-requirements.txt . # The runtime stage copies the built venv into a slim runtime container -FROM python:${PYTHON_VERSION}-slim as runtime +FROM python:${PYTHON_VERSION}-slim AS runtime # Add apt-get system dependecies for runtime here if needed RUN apt-get update && apt-get install -y --no-install-recommends \ ffmpeg \ diff --git a/README.md b/README.md index cbb0905..d5333fe 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ [![CI](https://github.com/DiamondLightSource/htss-rig-bluesky/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/htss-rig-bluesky/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/DiamondLightSource/htss-rig-bluesky/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/htss-rig-bluesky) -[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![PyPI](https://img.shields.io/pypi/v/htss-rig-bluesky.svg)](https://pypi.org/project/htss-rig-bluesky) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) # HTSS Rig Bluesky diff --git a/docs/_api.rst b/docs/_api.rst new file mode 100644 index 0000000..067ef75 --- /dev/null +++ b/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 htss_rig_bluesky and all its + subpackages + +API +=== + +.. autosummary:: + :toctree: _api + :template: custom-module-template.rst + :recursive: + + htss_rig_bluesky diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst new file mode 100644 index 0000000..9aeca54 --- /dev/null +++ b/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 %} diff --git a/docs/conf.py b/docs/conf.py index 96f8840..4c5f343 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,9 @@ -# 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 @@ -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 @@ -86,6 +89,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" diff --git a/docs/reference.md b/docs/reference.md index 3755a71..3c96141 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -7,6 +7,7 @@ Technical reference material including APIs and release notes. :glob: reference/* +API <_api/htss_rig_bluesky> genindex Release Notes ``` diff --git a/src/htss_rig_bluesky/__init__.py b/src/htss_rig_bluesky/__init__.py index 26d23ba..a2ffbf3 100644 --- a/src/htss_rig_bluesky/__init__.py +++ b/src/htss_rig_bluesky/__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__"] diff --git a/src/htss_rig_bluesky/__main__.py b/src/htss_rig_bluesky/__main__.py index 84c251f..a7b7303 100644 --- a/src/htss_rig_bluesky/__main__.py +++ b/src/htss_rig_bluesky/__main__.py @@ -1,16 +1,24 @@ +"""Interface for ``python -m htss_rig_bluesky``.""" + from argparse import ArgumentParser +from collections.abc import Sequence from . import __version__ __all__ = ["main"] -def main(args=None): +def main(args: Sequence[str] | None = None) -> None: + """Argument parser for the CLI.""" parser = ArgumentParser() - parser.add_argument("-v", "--version", action="version", version=__version__) - args = parser.parse_args(args) + parser.add_argument( + "-v", + "--version", + action="version", + version=__version__, + ) + parser.parse_args(args) -# test with: python -m htss_rig_bluesky if __name__ == "__main__": main()