Add Vale .ini for grammar linting and basic tests
This MR is for #38053 (closed) and adds:
-
a configuration file for Vale (https://github.com/errata-ai/vale), a grammar / language linter, into the
doc
directory -
a
doc/vale
directory to contain Vale styles -
Rudimentary tests, including:
- Oxford comma
- Spell-checking
- Sentence length > 25 words
- Unclear antecedents (the phrase 'this is')
The MR adheres to our value of MVC and does not attempt to implement Vale at a CI level.
To test out Vale locally with Visual Studio Code, complete the following actions:
-
Install Vale locally -
brew install vale
is easiest - For local editing in Visual Studio Code, install the Vale extension from https://marketplace.visualstudio.com/items?itemName=testthedocs.vale
- Close and reopen Visual Studio Code.
- Open the
doc
directory as a new workspace in Visual Studio Code. - Open the Markdown file you want to lint. The output pane at the bottom of the Visual Studio Code window should display a list of errors, warnings, and suggestions. The list is updated when you re-save the document.
(Other editors are also supported, but I have not tested them.)
cc @marcel.amirault as I know he's working on implementing markdownlint.
Todos before closing this MR:
-
Create issue to determine how capitalization tests can be implemented -
Create issue to add documentation around these changes once they've solidified -
Test if it's possible to define the regex for some of our current markdownlint tests to use them as vale tests instead
Edited by Amy Qualls