ci: add documentation checks (#3504)

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

@@ -0,0 +1,14 @@
+name: Main Documentation Checks
+
+on:
+  - pull_request
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number && format('pr{0}', github.event.number) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: doc/sphinx

doc/sphinx/.custom_wordlist.txt

@@ -0,0 +1,207 @@
+abi
+ABI
+adapter
+AppArmor
+appications
+AUR
+backend
+backends
+behavior
+Binutils
+Broadcom
+buf
+cgroup
+ci
+classDiagram
+CMake
+codebase
+Codecov
+CompositorAuthor
+coreXX
+CRTC
+Ctrl
+customize
+debian
+deps
+devel
+DisplayPlatform
+dispmanx
+Dispmanx
+DispmanX
+distros
+dlopen
+dma
+dmabuf
+drm
+DRM
+DSO
+DSOs
+EGL
+eglinfo
+eglstream
+EGLStreams
+egmde
+EGMDE
+EndToEnd
+etnaviv
+Etnaviv
+favorite
+filesystem
+flavors
+FloatingWindowManagerPolicy
+frontend
+Frontend
+FrontendWayland
+FrontendXWayland
+fs
+fullscreen
+gbm
+GC
+gcc
+github
+Github
+gl
+GLib
+glibc
+GPUs
+GTK
+hoc
+href
+https
+IdleHub
+Igalia
+IMX
+InputDispatcher
+InputPlatform
+intel
+io
+IoT
+IPC
+ish
+jenkins
+KDE's
+KDE’s
+KHR
+Khronos
+kms
+libEGL
+Libera
+libhybris
+libinput
+libmirclient
+libVA
+linux
+logind
+lomiri
+Lomiri
+lp
+lttng
+LTTng
+LWN
+maintainer's
+maximized
+Miaspects
+minimalistic
+mir
+miral
+MirAL
+mirco
+mircommon
+mircore
+Miriway
+miroil
+mirplatform
+mirserver
+MirServer
+mirserverlttng
+mirwayland
+mmal
+Multiarch
+MX
+nouveau
+nvidia
+Nvidia's
+Nvidia’s
+nxp
+ok
+OMX
+orchestrator
+organized
+paltform
+ppa
+PPAs
+preload
+preselects
+prober
+programmatically
+Protobuf
+qtmir
+Qtmir
+radeon
+raspberrypi
+rc
+renderables
+RenderingPlatform
+replug
+RPi
+runtime
+sanitizer
+Sanitizer
+sanitizers
+Sanitizers
+SBCs
+SceneChangeNotifiers
+SDL
+SHM
+snapcraft
+snapd
+SONAME
+SpinnerSplash
+subgraph
+subprocess
+sys
+testflinger
+Testflinger
+TilingWindowManagerPolicy
+toolchain
+toolchains
+toolkits
+Tooltip
+tracepoint
+tracepoints
+TSan
+UBports
+ubuntu
+udev
+UndefinedBehaviourSanitizer
+userland
+userspace
+UST
+vaapi
+VC
+VDPAU
+VideoCore
+vivante
+Vivante
+VNC
+vt
+vtable
+Vulkan
+wayland
+Wayland
+webkit
+WindowManagementPolicy
+WindowManagerTools
+WL
+wlcs
+WLCS
+workspaces
+XCB
+Xlib
+XLib
+Xorg
+Xwayland
+XWayland
+yaml
+Yay
+zwp

doc/sphinx/.sphinx/pa11y-ci.json

@@ -0,0 +1,11 @@
+{
+  "defaults": {
+    "chromeLaunchConfig": {
+      "args": [
+	"--no-sandbox"
+      ]
+    }
+  },
+  "reporter": "cli",
+  "standard": "WCAG2AA"
+}

doc/sphinx/.sphinx/spellingcheck.yaml

@@ -9,7 +9,7 @@ matrix:
     - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
-  - _build/**/*.html
+  - _build/**/*.html|!_build/**/api/**/*.html|!_build/genindex/index.html
   pipeline:
   - pyspelling.filters.html:
       comments: false
@@ -27,3 +27,6 @@ matrix:
       - div.visually-hidden
       - img
       - a.p-navigation__link
+      - li:matches(.toctree-l3, .toctree-l2) # ignore table of content tags
+      - div:matches(.mermaid)                # ignore mermaid.js diagrams
+      - div:matches(.brand, .sidebar-sticky) # ignore version hash in desktop and mobile views

doc/sphinx/Makefile

@@ -9,8 +9,30 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 VENVDIR       = $(SPHINXDIR)/venv
-PA11Y         = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+PA11Y         = $(SPHINXDIR)/node_modules/pa11y-ci/bin/pa11y-ci.js --config $(SPHINXDIR)/pa11y-ci.json
 VENV          = $(VENVDIR)/bin/activate
+WORKDIR	      = ../build_doc
+WORKSPHINX    = $(WORKDIR)/doc/sphinx
+PROJROOT      = ../..
+DEPS	      = cmake doxygen libboost-dev libboost-iostreams-dev \
+		libboost-filesystem-dev libboost-program-options-dev \
+		libboost-system-dev libdrm-dev libegl-dev libepoxy-dev \
+		libfreetype-dev libglib2.0-dev libgles2-mesa-dev \
+		libglm-dev libinput-dev liblttng-ust-dev libwayland-dev \
+		libxcb-composite0-dev libxcb-randr0-dev libxcursor-dev \
+		libxkbcommon-dev libxml++2.6-dev libyaml-cpp-dev xsltproc
+
+# If the environment variable `GITHUB_WORKFLOW` is empty, then we're running
+# locally and shouldn't depend on `_build/index.html` to build HTML (so even if
+# it exists, we'll rebuild)
+# On CI where the envvar is set, we should depend on `_build/index.html` so we
+# don't build multiple times (multiple invocations = multiple complete builds
+# even if files didn't change)
+ifeq ($(GITHUB_WORKFLOW), "")
+HTMLINDEX     = ""
+else
+HTMLINDEX     = $(WORKSPHINX)/_build/index.html
+endif
 
 .PHONY: help full-help woke-install pa11y-install install run html epub serve \
         clean clean-doc spelling linkcheck woke pa11y Makefile
@@ -36,6 +58,10 @@ full-help: $(VENVDIR)
 	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
 	@echo "Run 'make help' to see supported targets."
 
+configure:
+	. $(VENV); \
+	cmake $(PROJROOT) -B $(WORKDIR) -DMIR_ENABLE_TESTS=NO -DMIR_PLATFORM=x11;
+
 # Shouldn't assume that venv is available on Ubuntu by default; discussion here:
 # https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847
 $(SPHINXDIR)/requirements.txt:
@@ -60,22 +86,24 @@ woke-install:
 
 pa11y-install:
 	@type $(PA11Y) >/dev/null 2>&1 || { \
-			echo "Installing \"pa11y\" from npm... \n"; \
+			echo "Installing \"pa11y-ci\" from npm... \n"; \
 			mkdir -p $(SPHINXDIR)/node_modules/ ; \
-			npm install --prefix $(SPHINXDIR) pa11y; \
+			npm install --prefix $(SPHINXDIR) pa11y-ci; \
 		}
 
 install: $(VENVDIR)
+	sudo apt install -y $(DEPS)
 
-run: install
-	. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+run: install configure
+	. $(VENV); cd $(WORKSPHINX); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
-# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
-html: install
-	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+html: install configure
+	cd $(WORKSPHINX); \
+	. $(VENV); \
+	$(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
 
-epub: install
-	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+epub: install configure
+	. $(VENV); cd $(WORKSPHINX); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
 
 serve: html
 	cd "$(BUILDDIR)"; python3 -m http.server 8000
@@ -85,23 +113,25 @@ clean: clean-doc
 	rm -rf $(VENVDIR)
 	rm -f $(SPHINXDIR)/requirements.txt
 	rm -rf $(SPHINXDIR)/node_modules/
+	rm -r $(WORKDIR)
 
 clean-doc:
 	git clean -fx "$(BUILDDIR)"
 	rm -rf $(SPHINXDIR)/.doctrees
 
 spelling: html
-	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
+	. $(VENV) ; cd $(WORKSPHINX); python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
 
 linkcheck: install
-	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	. $(VENV) ; cd $(WORKSPHINX); $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
+# No need to go to $(WORKSPHINX) since it works on raw source files
 woke: woke-install
 	woke *.rst **/*.rst --exit-1-on-failure \
 	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
 
 pa11y: pa11y-install html
-	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+	$(PA11Y) $(shell find $(WORKSPHINX)/_build -name *.html -not -path '$(WORKSPHINX)/_build/api/*');
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/sphinx/how-to/getting_involved_in_mir.md

@@ -54,7 +54,7 @@ terminal you can start apps. For example:
 
     $ gedit
 
-To exit from miral-shell press Ctrl-Alt-BkSp.
+To exit from miral-shell press Ctrl-Alt-Backspace.
 
 You can install the Mir examples, headers and libraries you've built with:
 

doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md

@@ -78,7 +78,7 @@ Node: /dev/dri/card1
 You want to make sure that you have:
 - 1 Node
 - 1 or more Connector(s)
-- 1 or mor CRTC(s)
+- 1 or more CRTC(s)
 - 1 or more Plane(s)
 
 Finally, If you have a display connected, then one of your `Connector`s should read `Status: connected`. This `Connector` will also list many `Modes` that