Run documentation checks¶

The Sphinx Stack comes with several tests and checks that you can (and should!) run on your documentation before committing and pushing changes:

Accessibility check
Inclusive language check
Link check
Markdown lint check
Spelling check
Style guide linting
Vale exemptions

Accessibility check¶

The Sphinx Stack checks the accessibility of the documentation with Pa11y. It’s configured to check for Level AA conformity to the Web Content Accessibility Guidelines (WCAG) 2.2.

This check is only available locally; it is not part of the GitHub workflows in the Sphinx Stack.

To run the check, you must have npm and Pa11y installed. To install npm, refer to the installation guide for details. Then:

npm install pa11y

To check the accessibility of the documentation, run the following command in your /docs directory:

make pa11y

Configure¶

The pa11y.json file in the _dev directory provides basic defaults expected to be used for all teams; refrain from removing any unless absolutely necessary. Additional settings and options are detailed in the Pa11y README on GitHub.

Inclusive language check¶

The Sphinx Stack checks for inclusive language with a custom set of Vale rules. To check for inclusive language violations, run:

make woke

Configure¶

If you need to exempt single words or sections, follow the process in Vale exemptions.

Link check¶

The Sphinx Stack checks any links in your documentation with the Sphinx linkcheck builder. To validate the links, run:

make linkcheck

Configure¶

If you have links in the documentation that you don’t want to check, add them to the linkcheck_ignore list in the conf.py file.

Markdown lint check¶

The Sphinx Stack checks standards and consistency in Markdown files with the Markdown lint check. To check your Markdown files, run:

make lint-md

Configure¶

You can update the linting rules in the _dev/.pymarkdown.json file. Refer to the pymarkdown rules documentation for all the available rules.

Spelling check¶

The Sphinx Stack uses Vale to check the spelling in your documentation. It ignores inline code, code blocks, and URLs, but it does check the link text. To ensure there are no spelling errors in your documentation, run:

make spelling

Configure¶

If you need to exempt single words or sections, follow the process in Vale exemptions.

Style guide linting¶

The Sphinx Stack runs the Vale documentation linter configured with the rules of style guide To check your documentation with Vale, run:

make vale

Vale can run against individual files, directories, or globs. To check a specific target, run:

make vale TARGET=example.file
make vale TARGET=example-directory

If you run the linter against a directory, its subdirectories were also linted.

You can use wildcards to lint globs of files. For example, to run against all Markdown files within a directory, you’d run:

make vale TARGET=*.md

Configure¶

If you need to exempt single words or sections, follow the process in Vale exemptions.

Vale exemptions¶

The Inclusive language check, Spelling check, and Style guide linting all use Vale. These checks share a common syntax for exemptions and pull from the same .custom_wordlist.txt file. The style guide repository includes a common list of words that will be excluded from the checks.

A word¶

To ignore a single instance of a word, wrap it in the :vale-ignore: role. Ensure your conf.py file contains the appropriate class association in the rst_prolog:

rst_prolog = """
.. role:: vale-ignore
    :class: vale-ignore
"""

To ignore a word across your documentation, add it to your project’s .custom_wordlist.txt file.

Case sensitivity

Entries in .custom-wordlist are case-sensitive only when the word is capitalized. For instance:

Adding kustom will cause all instances of Kustom and kustom to be ignored.
Adding Kustom will cause only instances of Kustom to be ignored.

A section of text¶

To disable Vale for a section of text, use the following markup:

Markdown

<!-- vale off -->

This text will be ignored.

<!-- vale on -->

reST

.. vale off

This text will be ignored.

.. vale on

Directives¶

To disable Vale linting for Directives as a code block or admonitions, apply the vale-ignore class to the section:

Markdown

````{class} vale-ignore
```{code-block}

This content will be ignored by Vale.
```
````

reST

.. class:: vale-ignore
    .. code-block::

        This content will be ignored by Vale.

The class process isn’t be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. Also, the .. class:: directive for reST does not need to encapsulate content, it applies to the next logical block (which can be another directive or even a paragraph of content). The class option should only be used when other options aren’t suitable.

Hyphens and spaces

The checks may flag terms that contain hyphens or spaces.

For example, “Juju 3” wasn’t ignored by default, and needed to be added to be excepted with an upstream rule.