From ae9e242bf1d8fe75ade8382e2c4f11ae8888eab4 Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Thu, 6 Aug 2026 10:52:09 +0100 Subject: [PATCH 1/2] Lint reStructuredText prose with Vale Ban em dashes in reStructuredText using the pinned ClearProse Vale style package. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 3 +++ .pre-commit-config.yaml | 27 +++++++++++++++++++++++++++ .vale.ini | 12 ++++++++++++ pyproject.toml | 2 ++ 4 files changed, 44 insertions(+) create mode 100644 .vale.ini diff --git a/.gitignore b/.gitignore index 556e31308..1b5882e5e 100644 --- a/.gitignore +++ b/.gitignore @@ -112,3 +112,6 @@ secrets.tar src/*/_setuptools_scm_version.txt uv.lock + +# Vale styles downloaded by ``vale sync`` +styles/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0cd0ac391..4171919ae 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -288,6 +288,33 @@ repos: - *uv_version stages: [pre-commit] + # Vale enforces prose style rules, such as banning em dashes, in + # reStructuredText files. + # The rules come from the ``ClearProse`` package pinned in ``.vale.ini``, + # which ``vale sync`` downloads into the (gitignored) ``styles`` + # directory. + # Vale needs ``rst2html`` from Docutils on the ``PATH`` to parse + # reStructuredText. + - id: vale-sync + name: vale sync + entry: uv run --extra=dev vale sync + language: python + pass_filenames: false + types_or: [rst] + additional_dependencies: + - *uv_version + stages: [pre-commit] + + - id: vale + name: vale + entry: uv run --extra=dev vale + language: python + types_or: [rst] + require_serial: true + additional_dependencies: + - *uv_version + stages: [pre-commit] + - id: interrogate name: interrogate entry: uv run --extra=dev -m interrogate diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..2b57be049 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +StylesPath = styles +MinAlertLevel = error + +Packages = https://github.com/adamtheturtle/vale-style-clear-prose/releases/download/v1.0.1/ClearProse.zip + +[*.rst] +BasedOnStyles = ClearProse + +# Docutils does not know Sphinx roles such as `:ref:`, and renders their +# argument as ordinary prose. Ignoring role syntax keeps target names, which +# are not prose, out of the linter. +TokenIgnores = (:\w+:`[^`]*`) diff --git a/pyproject.toml b/pyproject.toml index 0410a5095..0d6cf82ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,6 +84,7 @@ optional-dependencies.dev = [ "towncrier==25.8.0", "ty==0.0.65", "types-requests==2.33.0.20260712", + "vale==3.13.0.0", "vulture==2.16", "vws-python-mock==2026.8.4.2", "vws-test-fixtures==2023.3.5", @@ -286,6 +287,7 @@ ignore = [ ".git_archival.txt", ".pre-commit-config.yaml", ".prettierrc", + ".vale.ini", ".yamlfmt", "CHANGELOG.rst", "ci", From e307e5d10046044e9c9f7963c797ac6186c71e52 Mon Sep 17 00:00:00 2001 From: Adam Dangoor Date: Thu, 6 Aug 2026 11:17:37 +0100 Subject: [PATCH 2/2] Use the ClearProse config package ClearProse 1.1.0 ships the ``TokenIgnores`` pattern for Sphinx roles in the package itself, so this repository no longer sets it. Co-Authored-By: Claude Opus 5 (1M context) --- .vale.ini | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.vale.ini b/.vale.ini index 2b57be049..8e3f9f747 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,12 +1,7 @@ StylesPath = styles MinAlertLevel = error -Packages = https://github.com/adamtheturtle/vale-style-clear-prose/releases/download/v1.0.1/ClearProse.zip +Packages = https://github.com/adamtheturtle/vale-style-clear-prose/releases/download/v1.1.0/ClearProse.zip [*.rst] BasedOnStyles = ClearProse - -# Docutils does not know Sphinx roles such as `:ref:`, and renders their -# argument as ordinary prose. Ignoring role syntax keeps target names, which -# are not prose, out of the linter. -TokenIgnores = (:\w+:`[^`]*`)