Setup Vale (prose linter) with a minimal unobtrusive configuration #281
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,5 +8,4 @@ __pycache__ | |
| *notes-from-review.md | ||
| *.idea* | ||
| # Grammar / syntax checkers | ||
| styles/ | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Configuration file for using Vale in the python-package-guide repository | ||
| # | ||
| # To disable checks on parts of a MarkDown or HTML file, delimit the section | ||
| # using these HTML comments: | ||
| # to disabled Vale checks after this line: <!-- vale off --> | ||
| # to enable Vale checks after this line: <!-- vale on --> | ||
| # | ||
| # To disable checks based on MarkDown scope, see IgnoredScopes. | ||
| # To disable checks on certain HTML elements, see IgnoredClasses. | ||
| # | ||
| # More information about the configuration can be found here: | ||
| # https://vale.sh/docs/topics/config | ||
|
|
||
|
|
||
| # Path to the styles directory, where style rules are defined | ||
| StylesPath = vale-styles | ||
|
|
||
| # Path to a dictionary folders inside the StylesPath config subdirectory. This | ||
| # folder can contain two files, accept.txt and reject.txt, with one word per | ||
| # line. These words will be used to check for spelling mistakes in addition to | ||
| # the internal dictionary, if the 'Vale' ruleset is enabled (see below) | ||
| # See https://vale.sh/docs/topics/vocab/#folder-structure for more details | ||
| Vocab = sample | ||
|
|
||
|
|
||
| # Checks are defined in sections by file type, like the one below for | ||
| # MarkDown. In each section you can enable groups of style rules, defined in folders | ||
| # inside the StylesPath directory. | ||
| # Use 'Vale' to enable the internal style rules and checks. | ||
|
|
||
| [*.md] | ||
| BasedOnStyles = package-guide-test |
|
There was a problem hiding this comment. @flpm so is this file where we add words that might be unusual but we want to accept as a part of our vocabulary? There was a problem hiding this comment. That is right, this is a way to customize the internal dictionary. But the dictionary checks are part of the internal Vale ruleset that is currently disabled in |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| extends: substitution | ||
|
There was a problem hiding this comment. Can you also please help me understand how this file works? Is there a way we could just create a list of words that we'd always want to spell a certain way rather than having a yml file for each word (if that makes sense?). i may not understand. so a list like this pyopensci: pyOpenSci etc? There was a problem hiding this comment. Sure. There are multiple extension points that can be used to customize Vale. This rule uses The first part of the map can also be a regular expression. I had to use two regular expressions in the PyPI rule because otherwise the lowercase string You are right about the list, to check for pyOpenSci case issues, you could either create a new rule like this one or even rename the file to something more generic like Likely you will run into similar false positives with the lowercase version of pyopensci matching URLs so you will need a regular expression to exclude them, but you could do something like I did for PyPI:
(? ) tells Vale it is a regexp This regexp matches For other extension points the structure is slightly different, for example for Here are more details about the extension points https://vale.sh/docs/topics/styles/#extension-points I put some example rules as examples (write-good ruleset) in There was a problem hiding this comment. thank you so much!! this makes sense. and i hadn't considered the word within a url so regex also makes a lot of sense to control for that! |
||
| message: Consider using '%s' instead of '%s' | ||
| level: warning | ||
| ignorecase: false | ||
| action: | ||
| name: replace | ||
| # swap maps tokens in form of bad: good | ||
| swap: | ||
| # lower case defined as regex to prevent false positives in URLs or other identifiers | ||
| - (?:\spypi[\.,]?\s): PyPI | ||
| - (?:\stestpypi[\.,;:]?\s): TestPyPI | ||
| - (?:\stest-pypi[\.,;:]?\s): TestPyPI | ||
| # other tests are defined with strings | ||
| - pyPi: PyPI | ||
| - pyPI: PyPI | ||
| - PYPI: PyPI | ||
| - PyPi: PyPI | ||
| - Pypi: PyPI | ||
| - testPyPI: TestPyPI | ||
| - testPYPI: TestPyPI | ||
| - TestPypi: TestPyPI | ||
| - TestPYPI: TestPyPI | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is so so great!! i'll try to review and get this merged tomorrow @flpm thank you again. we have so many open issues and pr's it's taking a bit longer than expected to merge things!
@kierisi i just wanted you to see this - notice that Filipe setup a rule for pypi to be PyPI and it catches that issue across our guidebook! we can now create a style guide that is checked in CI using this tool (and we can do the same on our website too)!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Because the current PyPI rule is set to warning and not an error, pre-commit will succeed in CI. But if the
level: warningis replaced withlevel: errorin PyPI.yml, pre-commit will fail .There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ahhhh ok perfect!