Setup Vale (prose linter) with a minimal unobtrusive configuration

flpm commented 1 month ago

What was done

Added vale as a dev dependency in pyproject.toml
Remove vale config file from git-ignore
Created the folder vale-styles to store vale style rules
Created a custom style rule set (package-guide-test) with one rule to check for incorrect capitalizations of PyPI (PyPI.yml)
Added the write-good rule set to serve as example (not enabled)
Created a very basic configuration file (.vale.ini)
Configured pre-commit to run vale
Used vale to fix all improper capitalizations found in the current MarkDown files
Excluded vale-styles folder from pre-commit codespell
Excluded vale-styles folder from sphinx build

The initial configuration is set to be unobtrusive: only the package-guide-test rule set is enabled and the PyPi rule generates warnings instead of errors (do not prevent commits).

With this configuration, vale can be run in the command line and in pre-commit, but pre-commit will not block commits that violate the rule because it is a warning.

Once the editorial team decides what style rules they would like to enforce, community-created rules can be installed or custom rules can be created in the vale-styles directory. I am happy to help with that if needed :raised_back_of_hand:

An example of running vale in the command line

If you save the following content as test.md:

# Test for Vale

PYPI is not how you should spell PyPI. This will trigger a Vale error on line 3, character 1.

The rule also checks for the correct spelling of TestPYPI, which is TestPyPI. This line will
also trigger a Vale error on line 5, character 50.

The rule should not trigger in cases where a lowercase capitalization is correct,
like here: https://pypi.org or test-pypi-search

Then run vale passing the proper path, you will see 2 warnings:

$ vale test.md

 test.md
 3:1   warning  Consider using 'PyPI' instead   package-guide-test.PyPI 
                of 'PYPI'                                               
 5:50  warning  Consider using 'TestPyPI'       package-guide-test.PyPI 
                instead of 'TestPYPI'                                   

✖ 0 errors, 2 warnings and 0 suggestions in 1 file.

Editor integration

Another interesting option is to run vale in the actual editor. Vale provides integrations to a bunch of common editors (Obsidian, VS Code, Emacs, Vim, etc). Just like with code linters, you get immediate feedback while writing and fix issues before you commit your contribution.

Here is what it looks like on VS Code.

screenshot