chore: fixes to adapt starter-pack to craft-cli

- fix spelling and update custom wordlist
- chore: make linkcheck ignore an internal reference
- fix various yaml formatting issues
- don't run the doc linting workflow twice
- chore: disabled autonamedtuple extension:

The problem: when running in Python3.8, the autonamedtuple extension
(part of sphinx-toolbox) fails to eval newer-style type annotations
(like "type[X]" instead of "typing.Type[X]"), even if the Python module
that has said code has the correct __future__ annotations.

This affects us because the documentation linters on CI run on Ubuntu
20.04, which has Python 3.8 by default. So the quicker fix here is to
disable the extension by instead enabling everything else in the toolbox
manually.

.github/workflows/automatic-doc-checks.yml

@@ -1,9 +1,11 @@
 name: Main Documentation Checks
 
 on:
-  - push
-  - pull_request
-  - workflow_dispatch
+  push:
+    branches:
+      - "main"
+  pull_request:
+  workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

docs/.custom_wordlist.txt

@@ -0,0 +1,21 @@
+appname
+args
+ArgumentParser
+backend
+cli
+CLI's
+GlobalArgument
+helptexts
+logfile
+pytest
+RecordingEmitter
+stderr
+stdout
+str
+Submodules
+subprocess
+subprocesses
+sysargs
+TOs
+tracebacks
+UX

docs/.readthedocs.yaml

@@ -17,11 +17,7 @@ sphinx:
   configuration: docs/conf.py
   fail_on_warning: false
 
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-formats:
-   - pdf
-
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-     - requirements: docs/.sphinx/requirements.txt
+  install:
+    - requirements: docs/.sphinx/requirements.txt

docs/.sphinx/spellingcheck.yaml

@@ -1,29 +1,29 @@
 matrix:
-- name: rST files
-  aspell:
-    lang: en
-    d: en_GB
-  dictionary:
-    wordlists:
-    - .wordlist.txt
-    - .custom_wordlist.txt
+  - name: rST files
+    aspell:
+      lang: en
+      d: en_GB
+    dictionary:
+      wordlists:
+        - .wordlist.txt
+        - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
-  sources:
-  - _build/**/*.html
-  pipeline:
-  - pyspelling.filters.html:
-      comments: false
-      attributes:
-      - title
-      - alt
-      ignores:
-      - code
-      - pre
-      - spellexception
-      - link
-      - title
-      - div.relatedlinks
-      - strong.command
-      - div.visually-hidden
-      - img
-      - a.p-navigation__link
+    sources:
+      - _build/**/*.html|!_build/**/craft_cli/**|!_build/genindex/**|!_build/craft_cli.*/**
+    pipeline:
+      - pyspelling.filters.html:
+          comments: false
+          attributes:
+            - title
+            - alt
+          ignores:
+            - code
+            - pre
+            - spellexception
+            - link
+            - title
+            - div.relatedlinks
+            - strong.command
+            - div.visually-hidden
+            - img
+            - a.p-navigation__link

docs/custom_conf.py

@@ -130,8 +130,30 @@
     "sphinx_design",
     "sphinx_copybutton",
     "sphinx-pydantic",
-    "sphinx_toolbox",
     "sphinx.ext.autodoc",
+    # NOTE: we can't add sphinx_toolbox here because it enables autonamedtuple
+    # and that extension fails to parse future-like annotations, even if the
+    # file has the correct __future__ import.
+    # So instead, we manually enable every other extension that sphinx_toolbox
+    # has.
+    # "sphinx_toolbox",
+    "sphinx_toolbox.assets",
+    "sphinx_toolbox.changeset",
+    "sphinx_toolbox.code",
+    "sphinx_toolbox.collapse",
+    "sphinx_toolbox.confval",
+    "sphinx_toolbox.decorators",
+    "sphinx_toolbox.formatting",
+    "sphinx_toolbox.installation",
+    "sphinx_toolbox.issues",
+    "sphinx_toolbox.latex",
+    "sphinx_toolbox.rest_example",
+    "sphinx_toolbox.shields",
+    "sphinx_toolbox.sidebar_links",
+    "sphinx_toolbox.source",
+    "sphinx_toolbox.wikipedia",
+    "sphinx_toolbox.more_autodoc.autoprotocol",
+    "sphinx_toolbox.more_autodoc.autotypeddict",
 ]
 
 # Add MyST extensions
@@ -168,6 +190,9 @@
 ############################################################
 
 ## Add any configuration that is not covered by the common conf.py file.
+
+linkcheck_ignore += [r"craft_cli.dispatcher.html#craft_cli.dispatcher.CommandGroup"]
+
 # Type hints configuration
 set_type_checking_flag = True
 typehints_fully_qualified = False

docs/explanations.rst

@@ -7,9 +7,9 @@ Explanations
 About the appropriate mode to initiate ``emit``
 ===============================================
 
-The first mandatory parameter of the ``emit`` object is ``mode``, which controls the initial verboseness level of the system.
+The first mandatory parameter of the ``emit`` object is ``mode``, which controls the initial verbosity level of the system.
 
-As the user can change the level later using global arguments when executing the application (this is the application default level), it's recommended to use ``EmitterMode.BRIEF``, unless the application needs to honor any external configuration or indication (e.g. a ``DEBUG`` environment variable).
+As the user can change the level later using global arguments when executing the application (this is the application default level), it's recommended to use ``EmitterMode.BRIEF``, unless the application needs to honour any external configuration or indication (e.g. a ``DEBUG`` environment variable).
 
 The values for ``mode`` are the following attributes of the ``EmitterMode`` enumerator:
 
@@ -39,7 +39,7 @@ Unless overridden when ``emit`` is initiated (see :ref:`how to do that <howto_ot
 Global and command specific arguments
 =====================================
 
-One of the functionalities that the Dispatcher provides is global arguments handling: options that will be recognized and used no matter the position in the command line because they are not specific to any command, but global to all commands and the application itself.
+One of the functionalities that the Dispatcher provides is global arguments handling: options that will be recognised and used no matter the position in the command line because they are not specific to any command, but global to all commands and the application itself.
 
 For example, all these application executions are equivalent:
 
@@ -230,7 +230,7 @@ E.g.::
         log_filepath=logpath,
     )
 
-It is only after this point that ``emit`` can be used for printing. Note that the mode is typically initialized to ``EmitterMode.BRIEF``. The user can control the emitter mode through global arguments. The ``Dispatcher``, as mentioned earlier, handles global arguments (including help). However, the ``Dispatcher`` only applies emitter mode changes during ``pre_parse_args()`` when parsing the global arguments (e.g. ``--verbosity=trace``) later on in the code.
+It is only after this point that ``emit`` can be used for printing. Note that the mode is typically initialised to ``EmitterMode.BRIEF``. The user can control the emitter mode through global arguments. The ``Dispatcher``, as mentioned earlier, handles global arguments (including help). However, the ``Dispatcher`` only applies emitter mode changes during ``pre_parse_args()`` when parsing the global arguments (e.g. ``--verbosity=trace``) later on in the code.
 
 E.g.::
 

docs/howtos.rst

@@ -125,7 +125,7 @@ Finally, if you want to build a hierarchy of errors in the application, you shou
 Define and use other global arguments
 =====================================
 
-To define more automatic global arguments than the ones provided automatically by ``Dispatcher`` (see :ref:`this explanation <expl_global_args>` for more information), use the ``GlobalArgument`` object to create all you need and pass them to the ``Dispatcher`` at instatiaton time.
+To define more automatic global arguments than the ones provided automatically by ``Dispatcher`` (see :ref:`this explanation <expl_global_args>` for more information), use the ``GlobalArgument`` object to create all you need and pass them to the ``Dispatcher`` at creation time.
 
 Check :class:`craft_cli.dispatcher.GlobalArgument` for more information about the parameters needed, but it's very straightforward to create these objects. E.g.::
 
@@ -175,7 +175,7 @@ Create unit tests for code that uses Craft CLI's Emitter
 
 The library provides two fixtures that simplifies the testing of code using the Emitter when using ``pytest``.
 
-One of the fixtures (``init_emitter``) is even set with ``autouse=True``, so it will automatically initialize the Emitter and tear it down after each test. This way there is nothing special you need to do in your code when testing it, just use it.
+One of the fixtures (``init_emitter``) is even set with ``autouse=True``, so it will automatically initialise the Emitter and tear it down after each test. This way there is nothing special you need to do in your code when testing it, just use it.
 
 The other fixture (``emitter``) is very useful to test code interaction with Emitter. It provides an internal recording emitter that has several methods which help to test its usage.