Documentation linting with vale

Vale is a command-line tool for linting text documents. It also supports linting *.rst files, so can be used for Sphinx documentation.

Only the most basic steps are described. For more info go to https://vale.sh/docs/vale-cli/installation/.

Setup

1. Install vale. Either download it from the release page extract it at a proper location (add directory to your PATH variable) or download via a package manager:

   macOS:

   $ brew install vale
   

   Windows:

   $ choco install vale
   

2. Open the project directory which contains the documents you want to lint.

3. Make sure the project’s Python interpreter has sphinx or docutils installed (to parse *.rst files, vale requires the rst2hmtl tool, which comes with either of them).

   Important

   Don’t use a sphinx or docutils installation from pipx (to have it available from outside of your project’s virtual environment, as vale expects it inside your Python environment.

4. In your project documentation directory create these additional directory and file:

   .
   ├── styles/
   └── .vale.ini
   

5. Define one or multiple styles to check your input texts against. Check the Package Hub for available styles.

   Hint

   You may adapt existing styles to your liking or define a custom style from scratch. Check https://vale.sh/docs/topics/styles/ for guidance.

   It happens that styles have conflicting rules. In that case either adapt the rule of any style or reduce the amount of styles in the configuration.

6. Open the .vale.ini file and define the config (here: Microsoft Writing Style Guide):

   StylesPath = ./.vale_styles
   MinAlertLevel = suggestion
   [*.{rst}]
   BasedOnStyles = Vale, Microsoft
   

   Hint

   Exchange the BasedOnStyles parameter value with your downloaded style.

7. Download and install external configuration sources via

   $ vale sync
   

   Warning

   Executing sync re-downloads all specified styles . Any adjustments to the original styles have been done are overwritten. It is highly advised to save a backup of your adjustments in a separate location before running sync or adding the styles folder to version control to revert files, if needed.

Hint

Additional styles

Other styles, not present on Package Hub may also be installed manually, but not via vale sync. To activate the style, add the style’s directory name to the BasedOnStyles option in .vale.ini.

Name	URL
gitlab	https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab

Usage

Important

Make sure your Python environment is activated before running vale.

To execute a check on a single document execute:

$ vale </path/to/some.rst>

It will list you all the detected violations. You may open the respective grammar file and edit the rules to your liking.