Skip to content

Lint reStructuredText prose with Vale to ban em dashes #3125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adamtheturtle merged 2 commits into from
Aug 6, 2026
Merged

Lint reStructuredText prose with Vale to ban em dashes #3125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ae9e242
Lint reStructuredText prose with Vale
adamtheturtle Aug 6, 2026
e307e5d
Use the ClearProse config package
adamtheturtle Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,3 +112,6 @@ secrets.tar
src/*/_setuptools_scm_version.txt

uv.lock

# Vale styles downloaded by ``vale sync``
styles/
27 changes: 27 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions .vale.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
StylesPath = styles
MinAlertLevel = error

Packages = https://github.com/adamtheturtle/vale-style-clear-prose/releases/download/v1.1.0/ClearProse.zip

@cursor cursor Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx roles lack TokenIgnores

Medium Severity

The [*.rst] section no longer sets TokenIgnores, so Vale can treat Sphinx inline role targets (for example :file: and :doc:) as prose. Docutils still renders those arguments as normal text when parsing reStructuredText, which can trigger ClearProse errors on non-prose strings such as paths and doc names.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit e307e5d. Configure here.

@adamtheturtle adamtheturtle Aug 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a defect, so no change made.

TokenIgnores moved rather than disappeared. ClearProse 1.1.0 ships as a Vale config package, so vale sync installs the pattern to styles/.vale-config/0-ClearProse.ini, which Vale reads before this project's own .vale.ini. Verified on this branch:

$ uv run --extra=dev vale ls-config | jq .TokenIgnores
{
  "*.rst": [
    "(:\\w+:`[^`]*`)"
  ]
}

The pattern matches any role name, so :file: and :doc: behave exactly as :ref: does. Linting this fixture:

See :doc:`some—doc` and :file:`a/b—c.txt` and :ref:`t—x`.

Prose with an em dash — here.

reports one alert, on the prose em dash on the last line, and nothing on the three role targets.

The upstream change is adamtheturtle/vale-style-clear-prose#1, and the reasoning for keeping this in the package rather than in every consumer is in the 1.1.0 changelog entry.


[*.rst]
BasedOnStyles = ClearProse
2 changes: 2 additions & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -286,6 +287,7 @@ ignore = [
".git_archival.txt",
".pre-commit-config.yaml",
".prettierrc",
".vale.ini",
".yamlfmt",
"CHANGELOG.rst",
"ci",
Expand Down