Skip to content

Add Vale .ini for grammar linting and basic tests

Amy Qualls requested to merge docs-aqualls-20200103-valetest into master

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

Merge request reports