diff --git a/docs/conf.py b/docs/conf.py index 279e576c..8124ed4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -84,7 +84,7 @@ # Common links that should be available on every page rst_epilog = """ .. _Diamond Light Source: http://www.diamond.ac.uk -.. _black: https://github.com/psf/black +.. _ruff: https://github.com/astral-sh/ruff .. _flake8: https://flake8.pycqa.org/en/latest/ .. _isort: https://github.com/PyCQA/isort .. _pyright: https://microsoft.github.io/pyright/#/ diff --git a/docs/explanations/decisions/0008-use-tox.md b/docs/explanations/decisions/0008-use-tox.md index dfef5130..3172aa1f 100644 --- a/docs/explanations/decisions/0008-use-tox.md +++ b/docs/explanations/decisions/0008-use-tox.md @@ -27,7 +27,7 @@ There are a number of things that CI needs to run: - pytest - black -- pyright +- mypy - flake8 - isort - build documentation @@ -45,7 +45,7 @@ under pytest that had a plugin, and isort under flake8: subgraph cluster_0 { label = "pytest" "pytest-black" - "pytest-pyright" + "pytest-mypy" subgraph cluster_1 { label = "pytest-flake8" "flake8-isort" @@ -69,14 +69,14 @@ To address this, the tree was rearranged: pytest black - pyright + mypy subgraph cluster_1 { label = "flake8" "flake8-isort" } ``` -If using VSCode, this will still run black, flake8 and pyright on file save, but +If using VSCode, this will still run black, flake8 and mypy on file save, but for those using other editors and for CI another solution was needed. Enter [pre-commit](https://pre-commit.com/). This allows hooks to be run at `git commit` time on just the files that have changed, as well as on all tracked @@ -87,7 +87,7 @@ $ pre-commit install ``` Finally tox was added to run all of the CI checks including -the documentation build. pyright was moved out of the pre-commit and into tox +the documentation build. mypy was moved out of the pre-commit and into tox because it was quite long running and therefore intrusive. tox can be invoked to run all the checks in parallel with: @@ -109,7 +109,7 @@ The graph now looks like: { label = "tox -p" pytest - pyright + mypy "sphinx-build" subgraph cluster_1 { label = "pre-commit" @@ -124,11 +124,11 @@ The graph now looks like: Now the workflow looks like this: -- Save file, VSCode runs black, flake8 and pyright on it +- Save file, VSCode runs black, flake8 and mypy on it - Run 'tox -p' and fix issues until it succeeds - Commit files and pre-commit runs black and flake8 on them (if the developer had not run tox then this catches some of the most common issues) -- Push to remote and CI runs black, flake8, pyright once on all files +- Push to remote and CI runs black, flake8, mypy once on all files (using tox), then pytest multiple times in a test matrix ## Consequences diff --git a/docs/reference/standards.rst b/docs/reference/standards.rst index 711cbbac..d4098737 100644 --- a/docs/reference/standards.rst +++ b/docs/reference/standards.rst @@ -9,7 +9,7 @@ Code Standards The code in this repository conforms to standards set by the following tools: -- black_ for code formatting +- ruff_ for code formatting - flake8_ for style checks - isort_ for import ordering - pyright_ for static type checking diff --git a/template/.devcontainer b/template/.devcontainer new file mode 120000 index 00000000..485dcb28 --- /dev/null +++ b/template/.devcontainer @@ -0,0 +1 @@ +../.devcontainer \ No newline at end of file diff --git a/template/.devcontainer/devcontainer.json b/template/.devcontainer/devcontainer.json deleted file mode 100644 index 96427ee4..00000000 --- a/template/.devcontainer/devcontainer.json +++ /dev/null @@ -1,50 +0,0 @@ -// For format details, see https://containers.dev/implementors/json_reference/ -{ - "name": "Python 3 Developer Container", - "build": { - "dockerfile": "../Dockerfile", - "target": "developer" - }, - "remoteEnv": { - "DISPLAY": "${localEnv:DISPLAY}" - }, - // Add the URLs of features you want added when the container is built. - "features": { - "ghcr.io/devcontainers/features/common-utils:1": { - "username": "none", - "upgradePackages": false - } - }, - "customizations": { - // Set *default* container specific settings.json values on container create. - "settings": { - "python.defaultInterpreterPath": "/venv/bin/python" - }, - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "ms-python.python", - "tamasfe.even-better-toml", - "redhat.vscode-yaml", - "ryanluker.vscode-coverage-gutters" - ] - } - }, - // Make sure the files we are mapping into the container exist on the host - "initializeCommand": "bash -c 'for i in $HOME/.inputrc; do [ -f $i ] || touch $i; done'", - "runArgs": [ - "--net=host", - "--security-opt=label=type:container_runtime_t" - ], - "mounts": [ - "source=${localEnv:HOME}/.ssh,target=/root/.ssh,type=bind", - "source=${localEnv:HOME}/.inputrc,target=/root/.inputrc,type=bind", - // map in home directory - not strictly necessary but useful - "source=${localEnv:HOME},target=${localEnv:HOME},type=bind,consistency=cached" - ], - // make the workspace folder the same inside and outside of the container - "workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind", - "workspaceFolder": "${localWorkspaceFolder}", - // After the container is created, install the python project in editable form - "postCreateCommand": "pip install -e '.[dev]'" -} \ No newline at end of file diff --git a/template/.pre-commit-config.yaml b/template/.pre-commit-config.yaml deleted file mode 100644 index 5bc9f001..00000000 --- a/template/.pre-commit-config.yaml +++ /dev/null @@ -1,23 +0,0 @@ -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 - hooks: - - id: check-added-large-files - - id: check-yaml - - id: check-merge-conflict - - - repo: local - hooks: - - id: black - name: Run black - stages: [commit] - language: system - entry: black --check --diff - types: [python] - - - id: ruff - name: Run ruff - stages: [commit] - language: system - entry: ruff - types: [python] diff --git a/template/.pre-commit-config.yaml b/template/.pre-commit-config.yaml new file mode 120000 index 00000000..da406220 --- /dev/null +++ b/template/.pre-commit-config.yaml @@ -0,0 +1 @@ +../.pre-commit-config.yaml \ No newline at end of file diff --git a/template/.vscode b/template/.vscode new file mode 120000 index 00000000..18144664 --- /dev/null +++ b/template/.vscode @@ -0,0 +1 @@ +../.vscode \ No newline at end of file diff --git a/template/.vscode/extensions.json b/template/.vscode/extensions.json deleted file mode 100644 index a1227b34..00000000 --- a/template/.vscode/extensions.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "recommendations": [ - "ms-vscode-remote.remote-containers", - "ms-python.python", - "tamasfe.even-better-toml", - "redhat.vscode-yaml", - "ryanluker.vscode-coverage-gutters", - "charliermarsh.Ruff" - ] -} diff --git a/template/.vscode/launch.json b/template/.vscode/launch.json deleted file mode 100644 index 3cda7432..00000000 --- a/template/.vscode/launch.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - // Use IntelliSense to learn about possible attributes. - // Hover to view descriptions of existing attributes. - // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 - "version": "0.2.0", - "configurations": [ - { - "name": "Debug Unit Test", - "type": "python", - "request": "launch", - "justMyCode": false, - "program": "${file}", - "purpose": [ - "debug-test" - ], - "console": "integratedTerminal", - "env": { - // The default config in pyproject.toml's "[tool.pytest.ini_options]" adds coverage. - // Cannot have coverage and debugging at the same time. - // https://github.com/microsoft/vscode-python/issues/693 - "PYTEST_ADDOPTS": "--no-cov" - }, - } - ] -} diff --git a/template/.vscode/settings.json.jinja b/template/.vscode/settings.json.jinja deleted file mode 100644 index 30439cc6..00000000 --- a/template/.vscode/settings.json.jinja +++ /dev/null @@ -1,21 +0,0 @@ -{ - "python.linting.pylintEnabled": false, - "python.linting.flake8Enabled": false, - "python.linting.enabled": true, - "python.testing.pytestArgs": [ - "--cov={{ package_name }}", - "--cov-report", - "xml:cov.xml" - ], - "python.testing.unittestEnabled": false, - "python.testing.pytestEnabled": true, - "python.formatting.provider": "black", - "python.languageServer": "Pylance", - "editor.formatOnSave": true, - "[python]": { - "editor.codeActionsOnSave": { - "source.fixAll.ruff": false, - "source.organizeImports.ruff": true - } - } -} diff --git a/template/.vscode/tasks.json b/template/.vscode/tasks.json deleted file mode 100644 index c999e864..00000000 --- a/template/.vscode/tasks.json +++ /dev/null @@ -1,16 +0,0 @@ -// See https://go.microsoft.com/fwlink/?LinkId=733558 -// for the documentation about the tasks.json format -{ - "version": "2.0.0", - "tasks": [ - { - "type": "shell", - "label": "Tests, lint and docs", - "command": "tox -p", - "options": { - "cwd": "${workspaceRoot}" - }, - "problemMatcher": [], - } - ] -} diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 49ea22fd..fcb4f789 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -24,7 +24,6 @@ requires-python = ">=3.7" [project.optional-dependencies] dev = [ - "black", "copier", "myst-parser", "pipdeptree", diff --git a/template/{% if sphinx %}docs{% endif %}/conf.py.jinja b/template/{% if sphinx %}docs{% endif %}/conf.py.jinja index a38102f9..961a01f4 100644 --- a/template/{% if sphinx %}docs{% endif %}/conf.py.jinja +++ b/template/{% if sphinx %}docs{% endif %}/conf.py.jinja @@ -105,15 +105,6 @@ intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)} # A dictionary of graphviz graph attributes for inheritance diagrams. inheritance_graph_attrs = {"rankdir": "TB"} -# Common links that should be available on every page -rst_epilog = """ -.. _Diamond Light Source: http://www.diamond.ac.uk -.. _black: https://github.com/psf/black -.. _ruff: https://beta.ruff.rs/docs/ -.. _pyright: https://microsoft.github.io/pyright/#/ -.. _pre-commit: https://pre-commit.com/ -""" - # Ignore localhost links for periodic check that links in docs are valid linkcheck_ignore = [r"http://localhost:\d+/"]