diff --git a/help-woke.rst b/help-woke.rst new file mode 100644 index 00000000..8bc2a488 --- /dev/null +++ b/help-woke.rst @@ -0,0 +1,57 @@ +=================================== +Inclusive language check exemptions +=================================== + +This page provides an overview of two inclusive language check exemption +methods for files written in reST format. See the `woke documentation`_ for +full coverage. + +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: + +.. code-block:: none + + :none:`wokeignore:rule=,` + +For instance: + +.. code-block:: none + + This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,` + +To exempt an element of a URL, it is recommended to use the standard reST +method of placing links at the bottom of the page (or in a separate file). In +this case, a comment line is placed immediately above the URL line. The comment +syntax is: + +.. code-block:: none + + .. wokeignore:rule= + +Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,` + +.. code-block:: none + + .. 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 file ``.wokeignore``: + +.. code-block:: none + + foo/bar.rst + +.. LINKS +.. _woke documentation: https://docs.getwoke.tech/ignore diff --git a/index.rst b/index.rst index 31dc9c3d..ea8c2534 100644 --- a/index.rst +++ b/index.rst @@ -18,4 +18,5 @@ More information is available in the `reStructuredText style guide`_. :maxdepth: 2 ReadMe + Inclusive language check exemptions Setup script diff --git a/readme.rst b/readme.rst index 3ed5bec1..5957c891 100644 --- a/readme.rst +++ b/readme.rst @@ -185,60 +185,18 @@ Its configuration is located in the ``.sphinx/spellingcheck.yaml`` file. To add exceptions for words flagged by the spelling check, edit the ``.custom_wordlist.txt`` file. You shouldn't edit ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. -Configure the inclusive-language check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you can't avoid non-inclusive language in some cases, you'll need to -configure exemptions for them. - -In-file exemptions -^^^^^^^^^^^^^^^^^^ - -Suppose a reST file has a link to some site you don't control, and the address -contains "\m\a\s\t\e\r" — a non-inclusive word. You can't change the link, -but the remainder of the file must be checked for inclusive language. Here the -``woke`` tool's `next-line ignore -`_ feature is -useful, as follows. - -If the link is in-line, move the definition to a line of its own (e.g. among -``.. LINKS`` at the bottom of the file). Above the definition, invoke the -``wokeignore`` rule for the offending word: - -.. code-block:: ReST - - .. LINKS - .. wokeignore:rule=master - .. _link anchor: https://some-external-site.io/master/some-page.html - -Exempt an entire file -^^^^^^^^^^^^^^^^^^^^^ - -If it's necessary *and safe*, you can exempt a whole file from -inclusive-language checks. To exempt ``docs/foo/bar.rst`` for example, add the -following line to ``.wokeignore``: - -.. code-block:: none - - foo/bar.rst - -.. note:: - - For ``.wokeignore`` to take effect, you must also move it into your - project's root directory. If you leave it in ``docs/``, the ``woke`` tool - won't find it and no files will be exempt. - -Change checked file-types and locations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, only reST files are checked for inclusive language — and only those -in the documentation folder (usually ``docs/``) and its subfolders. To check -Markdown files for example, or files outside the ``docs/`` subtree, you must -change how the ``woke`` tool is invoked. - -The ``woke`` command is issued from ``docs/Makefile``. The command's syntax -is out of scope here — consult the `woke User Guide -`_. +Customisation of inclusive language checks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 +change how the ``woke`` tool is invoked from within ``docs/Makefile`` (see +the `woke User Guide `_ for help). + +Some circumstances may require you to use some non-inclusive words. In such +cases you will need to create check-exemptions for them. See file +:doc:`help-woke` for how to do that. Configure the link check ~~~~~~~~~~~~~~~~~~~~~~~~