Inclusive language check¶

The inclusive language check uses woke to check for violations of inclusive language guidelines.

Install prerequisite software¶

To install woke, you need snap:

sudo apt install snapd

To install woke:

make woke-install

Run the inclusive language check¶

Ensure the documentation uses inclusive language:

make woke

Configure the inclusive language check¶

By default, the inclusive language check is applied only to reST files located under the documentation directory (usually docs). To check Markdown files, for example, or to use a location other than the docs sub-tree, you must override the ALLFILES variable in Makefile.sp (see Integrate the Makefiles).

You can find more information about available options in the woke User Guide.

Inclusive language check exemptions¶

Sometimes, you might need to use some non-inclusive words. In such cases, create check exemptions for them.

See the woke documentation for how to do this. The following sections provide some examples.

Exempt a word¶

To exempt an individual word, place a custom none role (defined in the canonical-sphinx-extensions Sphinx extension) anywhere on the line containing the word in question. The role syntax is:

:none:`wokeignore:rule=<SOME_WORD>,`

For instance:

This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,`

To exempt an element of a URL, use the standard reST method of placing links at the bottom of the page (or in a separate file) and place a comment line immediately above the URL line. The comment syntax is:

.. wokeignore:rule=<SOME_WORD>

Here is an example where a URL element contains the string “master”:

.. LINKS
.. wokeignore:rule=master
.. _link definition: https://some-external-site.io/master/some-page.html

You can now refer to the label link definition_ in the body of the text.

Exempt an entire file¶

A more drastic solution is to make an exemption for the contents of an entire file. For example, to exempt file docs/foo/bar.rst, add the following line to the file .wokeignore:

foo/bar.rst