fix: vale-spelling issues, adds vale documentation

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-- [ ] Have you updated `CHANGELOG.md` with relevant file changes?
+- [ ] Have you updated `CHANGELOG.md` with relevant non-documentation file changes?
 - [ ] Have you updated the documentation for this change?
 
------
+-----

docs/Makefile

@@ -138,21 +138,21 @@ woke: vale-install
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
 	@echo "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command"
-	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET)
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 
 vale: vale-install
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
 	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
-	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET)
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 
 vale-spelling: vale-install
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
 	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
-	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET)
 	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
 
 pdf-prep: install

docs/how-to/customise.rst

@@ -100,7 +100,7 @@ The following extensions are included by default:
 * ``sphinxcontrib.cairosvgconverter``
 * ``sphinx_last_updated_by_git``
 
-The `canonical_sphinx` extension is required for the starter pack.
+The ``canonical_sphinx`` extension is required for the starter pack.
 It automatically enables and sets default configurations for the following extensions:
 
 * ``custom-rst-roles``

docs/index.rst

@@ -36,4 +36,4 @@ In this documentation
       :link: /reference/index
       :link-type: doc
 
-      **Technical information** - understand the automatic checks and Sphinx capabilities.
+      **Technical information** - understand the automatic checks and Sphinx capabilities.

docs/reference/automatic_checks.rst

@@ -42,6 +42,7 @@ repository.
 The current defaults force usage of Canonical hosted runners, which some projects
 may not be able to use. You may select your own runners with an override, see line 7 below:
 
+.. class:: vale-ignore
 .. code-block::
    :emphasize-lines: 7
    :linenos:
@@ -62,6 +63,7 @@ changes are made to files in the ``docs/`` directory. If your project is structu
 differently, or if you want to run the checks on other directories, modify the trigger
 paths in the workflow files:
 
+.. class:: vale-ignore
 .. code-block:: yaml
    :emphasize-lines: 4
 

docs/reference/automatic_checks_styleguide.rst

@@ -60,3 +60,37 @@ For |RST|:
    This text will be ignored by Vale.
 
    .. vale on
+
+
+Exempt directives
+-----------------
+
+To disable Vale linting for a specific directive, you can apply a class to the section.
+
+For Markdown:
+
+.. code-block:: Markdown
+
+    ````{class} vale-ignore
+    ```{code-block}
+
+    This content will be ignored by Vale.
+    ```
+    ````
+
+.. note::
+
+    This should not be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default.
+
+For |RST|:
+
+.. code-block:: rst
+
+    .. class:: vale-ignore
+    .. code-block::
+
+        This content will be ignored by Vale.
+
+.. note:: 
+
+    The `.. class::` directive does not need to encapsulate content, it applies to the next logical block (which can be another directive or even a paragraph of content).