Skip to content

Commit 18d1551

Browse files
samcunliffesamcunliffe
authored
Update the linters page. (#276)
* Fixes #259. * Fixes the ordering part of #249 for this page.
1 parent 3342e23 commit 18d1551

File tree

1 file changed

+16
-34
lines changed

1 file changed

+16
-34
lines changed

‎docs/pages/linting.md

Lines changed: 16 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -5,43 +5,25 @@ layout: default
55

66
# Linting
77

8-
See [here for example configuration](https://github.com/UCL-ARC/python-tooling/blob/main/%7B%7Bcookiecutter.project_slug%7D%7D/.pre-commit-config.yaml) for some of these.
8+
See [here for an example configuration](https://github.com/UCL-ARC/python-tooling/blob/main/%7B%7Bcookiecutter.project_slug%7D%7D/.pre-commit-config.yaml) for some of these.
99

1010
## Code formatting
1111

12-
| Name | Short description | 🚦 | Used by |
13-
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
14-
| [ruff-format](https://github.com/astral-sh/ruff) | Like `black` but super fast. | 🟢 | |
15-
| [isort](https://pycqa.github.io/isort/) | Sorts imports alphabetically, splits into first/third party, works on python & cython code. | 🟢 | |
16-
| [pre-commit](https://pre-commit.com/) | Universal tool which performs a git hook on commit, allows you to run linters/formatters on any code. A tool to automatically run many of the tools listed below. | 🟢 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [RRED](https://github.com/UCL-ARC/rred-reports), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration) |
17-
| [ruff](https://github.com/astral-sh/ruff) | A very fast linter which incorporates a range of other linters. | 🟢 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [RRED](https://github.com/UCL-ARC/rred-reports), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration) |
18-
| [toml-sort](https://toml-sort.readthedocs.io/en/latest/) | Sorts TOML files which are now part of PEP 8. | 🟢 | |
19-
| [black](https://black.readthedocs.io/en/stable/) | Opinionated formatter, defaults to 88 characters per line. | 🟠 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration), [autodE](https://github.com/duartegroup/autodE) |
20-
| [autopep8](https://github.com/hhatto/autopep8) | Formatter which conforms to PEP 8. | 🟠 | |
21-
| [pycodestyle](https://pycodestyle.pycqa.org/en/latest/) | Linter which checks for errors. | 🟠 | |
22-
| [pyflakes](https://github.com/PyCQA/pyflakes) | Linter which checks for errors. | 🟠 | |
23-
| [pylint](https://pylint.readthedocs.io/en/latest/) | Linter which checks for errors. | 🟠 | |
24-
| [sourcery](https://sourcery.ai/) | An AI code reviewer which simplifies code, has a free version but can pay for fancier features. | 🟠 | |
25-
| [yapf](https://github.com/google/yapf) | Google formatter. | 🟠 | |
26-
| [flake8](https://flake8.pycqa.org/en/latest/) | Linter which complains if code doesn't follow a rule. Does not support modern `pyproject.toml` configuration. | 🔴 | |
27-
28-
<details>
29-
<summary> 🟢 explanation</summary>
30-
31-
We recommend a suite of 🟢 tools that we've used and work well together.
32-
33-
- Pre-commit is a useful framework tool to list several linters and run it automatically. It can be used to run all of our recommended linters.
34-
35-
- `black` is a nice _"no need to think"_ code formatter. If you have your own opinions about code style you might not like this. But it's widely used by almost all ARC python projects.
36-
37-
</details>
38-
39-
<details>
40-
<summary> 🔴 explanation</summary>
41-
42-
Flake8 is not recommended because it doesn't support `pyproject.toml` and [seemingly won't](https://github.com/PyCQA/flake8/issues/234#issuecomment-1206730688). There are now better and more flexible tools available.
43-
44-
</details>
12+
| Name | Short description | 🚦 | Used by |
13+
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
14+
| [pre-commit](https://pre-commit.com/) | Universal tool which performs a git hook on commit, allows you to run linters/formatters on any code. A tool to automatically run many of the tools listed below. | 🟢 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [RRED](https://github.com/UCL-ARC/rred-reports), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration) |
15+
| [ruff-format](https://github.com/astral-sh/ruff) | A drop-in replacement for `black` (and also super fast). A nice "no-need to think" code formatter. If you have your own opinions about code style, you might not like this. | 🟢 | |
16+
| [ruff](https://github.com/astral-sh/ruff) | A fast linter which incorporates a range of other linters. Notably [isort](https://pycqa.github.io/isort/) can be included as a [ruff rule](https://docs.astral.sh/ruff/rules/) (which we recommend). | 🟢 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [RRED](https://github.com/UCL-ARC/rred-reports), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration) |
17+
| [toml-sort](https://toml-sort.readthedocs.io/en/latest/) | Sorts TOML files which are now part of PEP 8. | 🟢 | |
18+
| [autopep8](https://github.com/hhatto/autopep8) | Formatter which conforms to PEP 8. | 🟠 | |
19+
| [black](https://black.readthedocs.io/en/stable/) | Opinionated formatter, defaults to 88 characters per line. Widely used, but we now recommend `ruff-format` in its place. | 🟠 | [DiRAC](https://github.com/UCL-ARC/dirac-swift-api), [Crabs Exploration](https://github.com/SainsburyWellcomeCentre/crabs-exploration), [autodE](https://github.com/duartegroup/autodE) |
20+
| [isort](https://pycqa.github.io/isort/) | Sorts imports alphabetically, splits into first/third party, works on python & cython code. We recommend this, but it can be included in `ruff`, which is simpler. | 🟠 | |
21+
| [pycodestyle](https://pycodestyle.pycqa.org/en/latest/) | Linter which checks for errors. | 🟠 | |
22+
| [pyflakes](https://github.com/PyCQA/pyflakes) | Linter which checks for errors. | 🟠 | |
23+
| [pylint](https://pylint.readthedocs.io/en/latest/) | Linter which checks for errors. | 🟠 | |
24+
| [sourcery](https://sourcery.ai/) | An AI code reviewer which simplifies code, has a free version but can pay for fancier features. | 🟠 | |
25+
| [yapf](https://github.com/google/yapf) | Google formatter. | 🟠 | |
26+
| [flake8](https://flake8.pycqa.org/en/latest/) | Linter which complains if code doesn't follow a rule. Does not support modern `pyproject.toml` configuration. | 🔴 | |
4527

4628
## Type checking
4729

0 commit comments

Comments
 (0)