docs: fix spelling checks in auto-generated material (#1069)

The reference section in the docs mostly consists of auto-generated
material.
Some of the material is not under our control (dconf) as it comes from
upstream packages.
As the main docs use GB spelling and the upstream US spelling, the
latter fail our spellcheck.

We should use GB spelling where possible to be consistent with the rest
of our docs and to prevent unnecessary context-switching when working on
the docs. We cannot change some of the reference material; doing so
could introduce inconsistencies with upstream and negatively affect the
searchability of the docs.

This PR removes reference material from our automated spellcheck.
It also adds a warning to the CONTRIBUTING.md about the autogenerated
docs, for future contributors who may wish to edit the files, along with
some other minor fixes.

UDENG-3685
UDENG-3686
UDENG-3687

CONTRIBUTING.md

@@ -63,12 +63,24 @@ Once merged to the main branch, `po` files, `README.md` with the command line re
 
 You can also contribute to the documentation. It uses [GitHub Markdown Format](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github).
 
-You can propose modifications in 2 ways:
+To contribute to the documentation edit the files in the `/docs/` directory after forking and cloning the repo.
+Each page on the [documentation website](https://canonical-adsys.readthedocs-hosted.com/en/stable/) also includes
+an edit button for making small changes, such as fixing typos.
 
-* Directly on the repo, in the `doc/` directory. Once merged, this will update the repository wiki automatically.
-* Via the [edit wiki link](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#editing-wiki-pages) of this repository. Once merged, this will update the main repository automatically.
+> [!WARNING]
+> Much of the reference documentation in `/docs/reference/` is auto-generated.
+> Editing the content of these files requires modifying `.go` and `.yaml` files found elsewhere in the repo.
+> Some references are generated using `dconf` keys from upstream packages and cannot be edited.
+> Changes made directly to reference files will be overwritten in the automation process.
+> If you want to propose a change to a reference page please make your edits in the relevant source files 
+> or contact someone on the ADSys team if you are uncertain how to do so.
 
-Each page is a different chapter, ordered with numbers, which is available with the command `adsysctl doc`.
+Documentation for the AD integration client `adsysctl` can be generated in the terminal with:
+
+```
+adsysctl doc [CHAPTER] [flags]
+```
+Each page is a different chapter ordered with numbers.
 
 ## Contributing to the code
 

docs/.sphinx/spellingcheck.yaml

@@ -9,7 +9,8 @@ matrix:
     - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
-  - _build/**/*.html
+      # check all docs except technical reference
+    - _build/**/*.html|!_build/reference/policies/**/*.html
   pipeline:
   - pyspelling.filters.html:
       comments: false
@@ -28,3 +29,4 @@ matrix:
       - img
       - a.p-navigation__link
       - a.contributor
+      - a.reference.internal # don't spellcheck refs hidden in html source

docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorisation/index.md → docs/reference/policies/Computer Policies/Ubuntu/Client management/Privilege Authorization/index.md

@@ -1,4 +1,4 @@
-# Privilege Authorisation
+# Privilege Authorization
 
 ```{toctree}
 :maxdepth: 99

docs/reference/policies/Computer Policies/Ubuntu/Client management/index.md

@@ -5,7 +5,7 @@
 
 Computer Scripts/index
 Power Management/index
-Privilege Authorisation/index
+Privilege Authorization/index
 System Drive Mapping/index
 System proxy configuration/index
 System-wide application confinement/index