diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 00000000000..7e28e2f16a6 --- /dev/null +++ b/.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 diff --git a/doc/sphinx/.custom_wordlist.txt b/doc/sphinx/.custom_wordlist.txt index e69de29bb2d..b58e5f175f9 100644 --- a/doc/sphinx/.custom_wordlist.txt +++ b/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 diff --git a/doc/sphinx/.sphinx/pa11y-ci.json b/doc/sphinx/.sphinx/pa11y-ci.json new file mode 100644 index 00000000000..e75a672c68c --- /dev/null +++ b/doc/sphinx/.sphinx/pa11y-ci.json @@ -0,0 +1,11 @@ +{ + "defaults": { + "chromeLaunchConfig": { + "args": [ + "--no-sandbox" + ] + } + }, + "reporter": "cli", + "standard": "WCAG2AA" +} diff --git a/doc/sphinx/.sphinx/pa11y.json b/doc/sphinx/.sphinx/pa11y.json deleted file mode 100644 index 8df0cb9cb52..00000000000 --- a/doc/sphinx/.sphinx/pa11y.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "chromeLaunchConfig": { - "args": [ - "--no-sandbox" - ] - }, - "reporter": "cli", - "standard": "WCAG2AA" -} \ No newline at end of file diff --git a/doc/sphinx/.sphinx/spellingcheck.yaml b/doc/sphinx/.sphinx/spellingcheck.yaml index fc9d3c5038f..8854307d874 100644 --- a/doc/sphinx/.sphinx/spellingcheck.yaml +++ b/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 diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile index 30ae665589d..cc82492bf99 100644 --- a/doc/sphinx/Makefile +++ b/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). diff --git a/doc/sphinx/how-to/getting_involved_in_mir.md b/doc/sphinx/how-to/getting_involved_in_mir.md index 266b44e337a..3a0645c2da2 100644 --- a/doc/sphinx/how-to/getting_involved_in_mir.md +++ b/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: diff --git a/doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md b/doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md index 8bcc6f1b076..501facc9934 100644 --- a/doc/sphinx/how-to/how-to-enable-graphics-core22-on-a-device.md +++ b/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