Minor rewording of precommit docs (#151)

* Minor rewording of precommit docs

* Further reorganization of pre-commit docs

* More details + examples for configuration of ruff

* Consistent terminology

* Use “rule category where appropriate”

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix ruff link

* fix indent of forbid-to-commit

---------

Co-authored-by: Philipp A <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Gregor Sturm <[email protected]>

{{cookiecutter.project_name}}/docs/template_usage.md

@@ -131,6 +131,10 @@ If your project is private, there are ways to enable docs rendering on [readthed
 check code for errors, inconsistencies and code styles, before the code
 is committed.
 
+This template uses a number of pre-commit checks. In this section we'll detail what is used, where they're defined, and how to modify these checks.
+
+#### Pre-commit CI
+
 We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit
 and pull-request.
 
@@ -150,85 +154,78 @@ The following pre-commit hooks are for code style and format:
     black on Python code in docs.
 -   [prettier](https://prettier.io/docs/en/index.html):
     standard code formatter for non-Python files (e.g. YAML).
+-   [ruff][] based checks:
+    -   [isort](https://beta.ruff.rs/docs/rules/#isort-i) (rule category: `I`):
+        sort module imports into sections and types.
+    -   [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (rule category: `D`):
+        pydocstyle extension of flake8.
+    -   [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (rule category: `TID`):
+        tidy module imports.
+    -   [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (rule category: `C4`):
+        write better list/set/dict comprehensions.
+    -   [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (rule category: `UP`):
+        upgrade syntax for newer versions of the language.
 
 The following pre-commit hooks are for errors and inconsistencies:
 
--   [ruff][]: Many configurable checks for Python code, see [Overview of Ruff checks](#overview-of-ruff-checks).
 -   [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks for text files.
     -   **detect-private-key**: checks for the existence of private keys.
     -   **check-ast**: check whether files parse as valid python.
     -   **end-of-file-fixer**: check files end in a newline and only a newline.
     -   **mixed-line-ending**: checks mixed line ending.
     -   **trailing-whitespace**: trims trailing whitespace.
     -   **check-case-conflict**: check files that would conflict with case-insensitive file systems.
--   **forbid-to-commit**: Make sure that `*.rej` files cannot be commited.
-    These files are created by the [automated template sync](#automated-template-sync)
-    if there's a merge conflict and need to be addressed manually.
+    -   **forbid-to-commit**: Make sure that `*.rej` files cannot be commited.
+        These files are created by the [automated template sync](#automated-template-sync)
+        if there's a merge conflict and need to be addressed manually.
+-   [ruff][] based checks:
+    -   [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (rule category: `F`):
+        various checks for errors.
+    -   [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (rule category: `E`, `W`):
+        various checks for errors.
+    -   [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (rule category: `B`):
+        find possible bugs and design issues in program.
+    -   [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (rule category: `BLE`):
+        checks for blind, catch-all `except` statements.
+    -   [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (rule category: `RUF`):
+        -   `RUF100`: remove unneccesary `# noqa` comments ()
+
+#### How to add or remove pre-commit checks
+
+The [pre-commit checks](#pre-commit-checks) check for both correctness and stylistic errors.
+In some cases it might overshoot and you may have good reasons to ignore certain warnings.
+This section shows you where these checks are defined, and how to enable/ disable them.
 
-[ruff]: https://beta.ruff.rs/docs/
+##### pre-commit
 
-#### Overview of Ruff checks
+You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file under the repository root.
+Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` (for `ruff` and `black`) or tool-specific
+config files, such as `.prettierrc.yml` for **prettier**.
 
-[Ruff][] implements several checks for Python code and docstrings.
-Therefore each check below mentions a the rule prefix that enables it when added to `pyproject.toml`.
-E.g. `isort` is enabled with:
+##### Ruff
 
-```toml
-[tool.ruff]
-select = [ ..., "I", ... ]
-```
+This template configures `ruff` through the `[tool.ruff]` entry in the `pyproject.toml`.
+For further information `ruff` configuration, see [the docs](https://beta.ruff.rs/docs/configuration/).
 
-The following checks are for code style and format:
-
--   [isort](https://beta.ruff.rs/docs/rules/#isort-i) (`I`):
-    sort module imports into sections and types.
--   [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (`D`):
-    pydocstyle extension of flake8.
--   [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (`TID`):
-    tidy module imports.
--   [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (`C4`):
-    write better list/set/dict comprehensions.
--   [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (`UP`):
-    upgrade syntax for newer versions of the language.
-
-The following checks are for errors and inconsistencies:
-
--   [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (`F`):
-    various checks for errors.
--   [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (`E`, `W`):
-    various checks for errors.
--   [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (`B`):
-    find possible bugs and design issues in program.
--   [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (`BLE`):
-    checks for blind, catch-all `except` statements.
--   [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (`RUF`):
-    -   `RUF100`: remove unneccesary `# noqa` comments.
-        See [How to ignore certain lint warnings](#how-to-ignore-certain-lint-warnings) for details.
-
-### How to disable or add pre-commit checks
-
--   To ignore lint warnigs from [Ruff][], see [How to ignore certain lint warnings](#how-to-ignore-certain-lint-warnings).
--   You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file.
-    Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific
-    config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**.
-
-### How to ignore certain lint warnings
-
-The [pre-commit checks](#pre-commit-checks) include [Ruff][] which checks
-for errors in Python files, including stylistic errors.
+Ruff assigns code to the rules it checks (e.g. `E401`) and groups them under a rule category (e.g. `E`).
+Rule categories are selectively enabled by including them under the `select` key:
 
-In some cases it might overshoot and you may have good reasons to ignore certain warnings.
-
-To ignore an specific error on a per-case basis, you can add a `# noqa: <rule>[, <rule>, …]` comment to the offending line.
-Specify the rule ID(s) to ignore, with e.g. `# noqa: E731`. Check the [Ruff guide][] for reference.
+```toml
+[tool.ruff]
+...
 
-The `RUF100` check will remove `noqa` IDs that are no longer necessary.
-If you want to add an ID that comes from a tool other than Ruff,
-add it to Ruff’s [`external = [...]`](https://beta.ruff.rs/docs/settings/#external) setting to prevent `RUF100` from removing it.
+select = [
+    "F",  # Errors detected by Pyflakes
+    "E",  # Error detected by Pycodestyle
+    "W",  # Warning detected by Pycodestyle
+    "I",  # isort
+    ...
+]
+```
 
-You can also disable certain error messages for the entire project.
-To do so, edit the `[tool.ruff]` section in `pyproject.toml` in the root of the repository.
-Add the rule ID(s) you want to ignore and don't forget to add a comment explaining why.
+The `ignore` entry is used to disable specific rules for the entire project.
+Add the rule code(s) you want to ignore and don't forget to add a comment explaining why.
+You can find a long list of checks that this template disables by default sitting there already.
 
 ```toml
 ignore = [
@@ -239,6 +236,25 @@ ignore = [
 ]
 ```
 
+Checks can be ignored per-file (or glob pattern) with `[tool.ruff.per-file-ignores]`.
+
+```toml
+[tool.ruff.per-file-ignores]
+"docs/*" = ["I"]
+"tests/*" = ["D"]
+"*/__init__.py" = ["F401"]
+```
+
+To ignore a specific rule on a per-case basis, you can add a `# noqa: <rule>[, <rule>, …]` comment to the offending line.
+Specify the rule code(s) to ignore, with e.g. `# noqa: E731`. Check the [Ruff guide][] for reference.
+
+```{note}
+The `RUF100` check will remove rule codes that are no longer necessary from `noqa` comments.
+If you want to add a code that comes from a tool other than Ruff,
+add it to Ruff’s [`external = [...]`](https://beta.ruff.rs/docs/settings/#external) setting to prevent `RUF100` from removing it.
+```
+
+[ruff]: https://beta.ruff.rs/docs/
 [ruff guide]: https://beta.ruff.rs/docs/configuration/#suppressing-errors
 
 ### API design