From a5b0c5338774a03812fcbf95396e875d8ba6d168 Mon Sep 17 00:00:00 2001 From: Gary Yendell Date: Tue, 17 Sep 2024 10:59:20 +0000 Subject: [PATCH] Rename project to fastcs-eiger and update to copier template 2.3.0 --- .copier-answers.yml | 10 +++-- .github/CONTRIBUTING.md | 6 +-- .github/pages/make_switcher.py | 14 ++++--- .gitignore | 1 + .vscode/launch.json | 4 +- Dockerfile | 2 +- README.md | 25 ++++++------ README.rst | 39 ------------------- catalog-info.yaml | 6 +-- docs/_api.rst | 16 ++++++++ docs/_templates/custom-module-template.rst | 37 ++++++++++++++++++ docs/conf.py | 27 ++++++++----- docs/how-to/run-container.md | 6 +-- docs/reference.md | 4 +- docs/reference/api.md | 17 -------- docs/tutorials/installation.md | 6 +-- pyproject.toml | 12 +++--- .../__init__.py | 0 .../__main__.py | 6 +-- .../eiger_controller.py | 2 +- .../http_connection.py | 0 tests/conftest.py | 12 ++++-- tests/system/test_introspection.py | 2 +- tests/test_cli.py | 4 +- tests/test_controller.py | 2 +- 25 files changed, 138 insertions(+), 122 deletions(-) delete mode 100644 README.rst create mode 100644 docs/_api.rst create mode 100644 docs/_templates/custom-module-template.rst delete mode 100644 docs/reference/api.md rename src/{eiger_fastcs => fastcs_eiger}/__init__.py (100%) rename src/{eiger_fastcs => fastcs_eiger}/__main__.py (92%) rename src/{eiger_fastcs => fastcs_eiger}/eiger_controller.py (99%) rename src/{eiger_fastcs => fastcs_eiger}/http_connection.py (100%) diff --git a/.copier-answers.yml b/.copier-answers.yml index 7f8da05..6b0dc8c 100644 --- a/.copier-answers.yml +++ b/.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: gary.yendell@diamond.ac.uk 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 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ae54a46..52a2004 100644 --- a/.github/CONTRIBUTING.md +++ b/.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). 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/.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/.vscode/launch.json b/.vscode/launch.json index 51d3d25..968394e 100644 --- a/.vscode/launch.json +++ b/.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"] diff --git a/Dockerfile b/Dockerfile index 0915542..fc706cf 100644 --- a/Dockerfile +++ b/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"] diff --git a/README.md b/README.md index ec4b6b7..ce53126 100644 --- a/README.md +++ b/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 | +Source | :---: | :---: -PyPI | `pip install eiger-fastcs` -Docker | `docker run ghcr.io/diamondlightsource/eiger-fastcs:latest` -Documentation | -Releases | - +PyPI | `pip install fastcs-eiger` +Docker | `docker run ghcr.io/diamondlightsource/fastcs-eiger:latest` +Documentation | +Releases | -See https://diamondlightsource.github.io/eiger-fastcs for more detailed documentation. +See https://diamondlightsource.github.io/fastcs-eiger for more detailed documentation. diff --git a/README.rst b/README.rst deleted file mode 100644 index 563f9ba..0000000 --- a/README.rst +++ /dev/null @@ -1,39 +0,0 @@ -Eiger FastCS -============ - -|code_ci| |docs_ci| |coverage| |pypi_version| |license| - -A FastCS backend developed for the Dectris Eiger Detector. - -============== ============================================================== -PyPI ``pip install eiger-fastcs`` -Source code https://github.com/DiamondLightSource/eiger-fastcs -Documentation https://DiamondLightSource.github.io/eiger-fastcs -Releases https://github.com/DiamondLightSource/eiger-fastcs/releases -============== ============================================================== - -.. |code_ci| image:: https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/code.yml/badge.svg?branch=main - :target: https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/code.yml - :alt: Code CI - -.. |docs_ci| image:: https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/docs.yml/badge.svg?branch=main - :target: https://github.com/DiamondLightSource/eiger-fastcs/actions/workflows/docs.yml - :alt: Docs CI - -.. |coverage| image:: https://codecov.io/gh/DiamondLightSource/eiger-fastcs/branch/main/graph/badge.svg - :target: https://codecov.io/gh/DiamondLightSource/eiger-fastcs - :alt: Test Coverage - -.. |pypi_version| image:: https://img.shields.io/pypi/v/eiger-fastcs.svg - :target: https://pypi.org/project/eiger-fastcs - :alt: Latest PyPI version - -.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 - :alt: Apache License - -.. - Anything below this line is used when viewing README.rst and will be replaced - when included in index.rst - -See https://DiamondLightSource.github.io/eiger-fastcs for more detailed documentation. diff --git a/catalog-info.yaml b/catalog-info.yaml index 183e12e..86ffbbf 100644 --- a/catalog-info.yaml +++ b/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 diff --git a/docs/_api.rst b/docs/_api.rst new file mode 100644 index 0000000..0a6cca6 --- /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 fastcs_eiger and all its + subpackages + +API +=== + +.. autosummary:: + :toctree: _api + :template: custom-module-template.rst + :recursive: + + fastcs_eiger 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 4a06943..bba8d99 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 @@ -10,15 +11,15 @@ 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 diff --git a/docs/how-to/run-container.md b/docs/how-to/run-container.md index ccb74b9..dd597ba 100644 --- a/docs/how-to/run-container.md +++ b/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`. diff --git a/docs/reference.md b/docs/reference.md index 7201174..d5ea602 100644 --- a/docs/reference.md +++ b/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 +Release Notes ``` diff --git a/docs/reference/api.md b/docs/reference/api.md deleted file mode 100644 index 9e20234..0000000 --- a/docs/reference/api.md +++ /dev/null @@ -1,17 +0,0 @@ -# API - -```{eval-rst} -.. automodule:: eiger_fastcs - - ``eiger_fastcs`` - ----------------------------------- -``` - -This is the internal API reference for eiger_fastcs - -```{eval-rst} -.. data:: eiger_fastcs.__version__ - :type: str - - Version number as calculated by https://github.com/pypa/setuptools_scm -``` diff --git a/docs/tutorials/installation.md b/docs/tutorials/installation.md index de09923..8c84226 100644 --- a/docs/tutorials/installation.md +++ b/docs/tutorials/installation.md @@ -24,19 +24,19 @@ $ source /path/to/venv/bin/activate You can now use `pip` to install the library and its dependencies: ``` -$ python3 -m pip install eiger-fastcs +$ python3 -m pip install fastcs-eiger ``` If you require a feature that is not currently released you can also install from github: ``` -$ python3 -m pip install git+https://github.com/DiamondLightSource/eiger-fastcs.git +$ python3 -m pip install git+https://github.com/DiamondLightSource/fastcs-eiger.git ``` The library should now be installed and the commandline interface on your path. You can check the version that has been installed by typing: ``` -$ eiger-fastcs --version +$ fastcs-eiger --version ``` diff --git a/pyproject.toml b/pyproject.toml index 2104f71..de27f31 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools>=64", "setuptools_scm[toml]>=8"] build-backend = "setuptools.build_meta" [project] -name = "eiger-fastcs" +name = "fastcs-eiger" classifiers = [ "Development Status :: 3 - Alpha", "License :: OSI Approved :: Apache Software License", @@ -45,17 +45,17 @@ dev = [ ] [project.scripts] -eiger-fastcs = "eiger_fastcs.__main__:app" +fastcs-eiger = "fastcs_eiger.__main__:main" [project.urls] -GitHub = "https://github.com/DiamondLightSource/eiger-fastcs" +GitHub = "https://github.com/DiamondLightSource/fastcs-eiger" [[project.authors]] # Further authors may be added by duplicating this section email = "gary.yendell@diamond.ac.uk" name = "Gary Yendell" [tool.setuptools_scm] -version_file = "src/eiger_fastcs/_version.py" +version_file = "src/fastcs_eiger/_version.py" [tool.mypy] ignore_missing_imports = true # Ignore missing stubs in imported modules @@ -71,7 +71,7 @@ filterwarnings = "error" testpaths = "docs src tests" [tool.coverage.run] -data_file = "/tmp/eiger_fastcs.coverage" +data_file = "/tmp/fastcs_eiger.coverage" [tool.coverage.paths] # Tests are run from installed location, map back to the src directory @@ -97,7 +97,7 @@ allowlist_externals = commands = pre-commit: pre-commit run --all-files --show-diff-on-failure {posargs} type-checking: mypy src tests {posargs} - tests: pytest --cov=eiger_fastcs --cov-report term --cov-report xml:cov.xml {posargs} + tests: pytest --cov=fastcs_eiger --cov-report term --cov-report xml:cov.xml {posargs} docs: sphinx-{posargs:build -EW --keep-going} -T docs build/html """ diff --git a/src/eiger_fastcs/__init__.py b/src/fastcs_eiger/__init__.py similarity index 100% rename from src/eiger_fastcs/__init__.py rename to src/fastcs_eiger/__init__.py diff --git a/src/eiger_fastcs/__main__.py b/src/fastcs_eiger/__main__.py similarity index 92% rename from src/eiger_fastcs/__main__.py rename to src/fastcs_eiger/__main__.py index 8ad6b43..ef64e25 100644 --- a/src/eiger_fastcs/__main__.py +++ b/src/fastcs_eiger/__main__.py @@ -6,8 +6,8 @@ from fastcs.backends.epics.backend import EpicsBackend from fastcs.backends.epics.gui import EpicsGUIOptions -from eiger_fastcs import __version__ -from eiger_fastcs.eiger_controller import EigerController +from fastcs_eiger import __version__ +from fastcs_eiger.eiger_controller import EigerController __all__ = ["main"] @@ -67,6 +67,6 @@ def asyncio(ip: str = EigerIp, port: int = EigerPort): backend.run_interactive_session() -# test with: python -m eiger_fastcs +# test with: python -m fastcs_eiger if __name__ == "__main__": app() diff --git a/src/eiger_fastcs/eiger_controller.py b/src/fastcs_eiger/eiger_controller.py similarity index 99% rename from src/eiger_fastcs/eiger_controller.py rename to src/fastcs_eiger/eiger_controller.py index 76c1390..74a76e6 100644 --- a/src/eiger_fastcs/eiger_controller.py +++ b/src/fastcs_eiger/eiger_controller.py @@ -12,7 +12,7 @@ from fastcs.wrappers import command, scan from PIL import Image -from eiger_fastcs.http_connection import HTTPConnection, HTTPRequestError +from fastcs_eiger.http_connection import HTTPConnection, HTTPRequestError # Keys to be ignored when introspecting the detector to create parameters IGNORED_KEYS = [ diff --git a/src/eiger_fastcs/http_connection.py b/src/fastcs_eiger/http_connection.py similarity index 100% rename from src/eiger_fastcs/http_connection.py rename to src/fastcs_eiger/http_connection.py diff --git a/tests/conftest.py b/tests/conftest.py index d5cdd5f..ebe9c10 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,4 +1,5 @@ import os +from typing import Any import pytest @@ -7,9 +8,14 @@ if os.getenv("PYTEST_RAISE", "0") == "1": @pytest.hookimpl(tryfirst=True) - def pytest_exception_interact(call): - raise call.excinfo.value + def pytest_exception_interact(call: pytest.CallInfo[Any]): + if call.excinfo is not None: + raise call.excinfo.value + else: + raise RuntimeError( + f"{call} has no exception data, an unknown error has occurred" + ) @pytest.hookimpl(tryfirst=True) - def pytest_internalerror(excinfo): + def pytest_internalerror(excinfo: pytest.ExceptionInfo[Any]): raise excinfo.value diff --git a/tests/system/test_introspection.py b/tests/system/test_introspection.py index bb88406..6bb0a0c 100644 --- a/tests/system/test_introspection.py +++ b/tests/system/test_introspection.py @@ -9,7 +9,7 @@ from fastcs.attributes import AttrR from fastcs.datatypes import Float -from eiger_fastcs.eiger_controller import EigerController, EigerParameter +from fastcs_eiger.eiger_controller import EigerController, EigerParameter HERE = Path(__file__).parent diff --git a/tests/test_cli.py b/tests/test_cli.py index 47b02e8..407aac6 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1,10 +1,10 @@ import subprocess import sys -from eiger_fastcs import __version__ +from fastcs_eiger import __version__ def test_cli_version(): - cmd = [sys.executable, "-m", "eiger_fastcs", "--version"] + cmd = [sys.executable, "-m", "fastcs_eiger", "--version"] stdout = subprocess.check_output(cmd).decode().strip().split("\n") assert __version__ in stdout diff --git a/tests/test_controller.py b/tests/test_controller.py index dea76ae..fd8950e 100644 --- a/tests/test_controller.py +++ b/tests/test_controller.py @@ -1,7 +1,7 @@ import pytest from pytest_mock import MockerFixture -from eiger_fastcs.eiger_controller import EigerController +from fastcs_eiger.eiger_controller import EigerController @pytest.mark.asyncio