Refactor out woke instructions (#158)

* Refactor out woke instructions

Signed-off-by: Peter Matulis <peter.matulis@canonical.com>

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=<SOME_WORD>,`
+
+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=<SOME_WORD>
+
+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

index.rst

@@ -18,4 +18,5 @@ More information is available in the `reStructuredText style guide`_.
    :maxdepth: 2
 
    ReadMe <readme>
+   Inclusive language check exemptions <help-woke>
    Setup script <setup-script>

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
-<https://docs.getwoke.tech/ignore/#in-line-and-next-line-ignoring>`_ 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
-<https://docs.getwoke.tech/usage/#file-globs>`_.
+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 <https://docs.getwoke.tech/usage/#file-globs>`_ 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
 ~~~~~~~~~~~~~~~~~~~~~~~~