Merge ~rkratky/ubuntu-governance-docs:update-starter-pack into ubuntu-governance-docs:main

[Robert Krátký]

Update the Docs Started Pack to latest version

* Merge Makefiles
* Adapt templates and config for Launchpad
* Add new features (metrics, vale linting)
* Remove unused artifacts
* Various small enhancements

diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
index e69de29..01abb2d 100644
--- a/docs/.custom_wordlist.txt
+++ b/docs/.custom_wordlist.txt
@@ -0,0 +1,24 @@
+# Leave a blank line at the end of this file to support concatenation
+cjk
+cryptographically
+dvipng
+fonts
+freefont
+github
+GPG
+gyre
+https
+lang
+latexmk
+otf
+plantuml
+tex
+texlive
+TOC
+utils
+WCAG
+xetex
+xindy
+kustom
+wordlist
+txt
diff --git a/docs/.gitignore b/docs/.gitignore
index da6f688..bf16e0d 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,14 +1,25 @@
-/*env*/
+# Environment
+*env*/
 .sphinx/venv/
+
+# Sphinx
 .sphinx/warnings.txt
 .sphinx/.wordlist.dic
 .sphinx/.doctrees/
 .sphinx/node_modules/
-package*.json
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
 _build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
 .DS_Store
 __pycache__
 .idea/
 .vscode/
-.sphinx/styles/*
-.sphinx/vale.ini
\ No newline at end of file
diff --git a/docs/.sphinx/.markdownlint.json b/docs/.sphinx/.markdownlint.json
new file mode 100644
index 0000000..f42753f
--- /dev/null
+++ b/docs/.sphinx/.markdownlint.json
@@ -0,0 +1,27 @@
+{
+    "default": false,
+    "MD003": {
+        "style": "atx"
+    },
+    "MD013": {
+        "code_blocks": false,
+        "tables": false,
+        "stern": true,
+        "line_length": 150
+    },
+    "MD014": true,
+    "MD018": true,
+    "MD022": true,
+    "MD023": true,
+    "MD026": {
+        "punctuation": ".,;。，；"
+    },
+    "MD031": {
+        "list_items": false
+    },
+    "MD032": true,
+    "MD035": true,
+    "MD042": true,
+    "MD045": true,
+    "MD052": true
+}
\ No newline at end of file
diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/.sphinx/.pre-commit-config.yaml
new file mode 100644
index 0000000..07e0b48
--- /dev/null
+++ b/docs/.sphinx/.pre-commit-config.yaml
@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: make-spelling
+        name: Run make spelling
+        entry: make -C docs spelling
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-linkcheck
+        name: Run make linkcheck
+        entry: make -C docs linkcheck
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-woke
+        name: Run make woke
+        entry: make -C docs woke
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt
index fb4137d..be5021a 100644
--- a/docs/.sphinx/.wordlist.txt
+++ b/docs/.sphinx/.wordlist.txt
@@ -1,13 +1,15 @@
-# This wordlist is from the Sphinx starter pack and should not be
-# modified. Add any custom terms to .custom_wordlist.txt instead.
-
+ACME
+ACME's
 addons
+AGPLv
 API
 APIs
 balancer
 Charmhub
 CLI
+DCO
 Diátaxis
+Dqlite
 dropdown
 EBS
 EKS
@@ -53,6 +55,7 @@ RTD
 subdirectories
 subfolders
 subtree
+TODO
 Ubuntu
 UI
 UUID
diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png
deleted file mode 100644
index 7f175e4..0000000
Binary files a/docs/.sphinx/_static/favicon.png and /dev/null differ
diff --git a/docs/.sphinx/_static/project_specific.css b/docs/.sphinx/_static/project_specific.css
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/.sphinx/_static/project_specific.css
diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png
deleted file mode 100644
index f6f6e5a..0000000
Binary files a/docs/.sphinx/_static/tag.png and /dev/null differ
diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html
new file mode 100644
index 0000000..2d118a8
--- /dev/null
+++ b/docs/.sphinx/_templates/footer.html
@@ -0,0 +1,111 @@
+{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
+
+<div class="related-pages">
+  {# mod: Per-page navigation #}
+  {% if meta %}
+    {% if 'sequential_nav' in meta %}
+      {% set sequential_nav = meta.sequential_nav %}
+    {% endif %}  
+  {% endif %}
+  {# mod: Conditional wrappers to control page navigation buttons #}
+  {% if sequential_nav != "none" -%}
+    {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+      <a class="next-page" href="{{ next.link }}">
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Next") }}</span>
+          </div>
+          <div class="title">{{ next.title }}</div>
+        </div>
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </a>
+    {%- endif %}
+    {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+      <a class="prev-page" href="{{ prev.link }}">
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Previous") }}</span>
+          </div>
+          {% if prev.link == pathto(root_doc) %}
+            <div class="title">{{ _("Home") }}</div>
+          {% else %}
+            <div class="title">{{ prev.title }}</div>
+          {% endif %}
+        </div>
+      </a>
+    {%- endif %}
+  {%- endif %}
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    {%- if show_copyright %}
+    <div class="copyright">
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e -%}
+          <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e -%}
+          Copyright &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+
+    {# mod: removed "Made with" #}
+
+    {%- if last_updated -%}
+    <div class="last-updated">
+      {% trans last_updated=last_updated|e -%}
+        Last updated on {{ last_updated }}
+      {%- endtrans -%}
+    </div>
+    {%- endif %}
+
+    {%- if show_source and has_source and sourcename %}
+    <div class="show-source">
+      <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">Show source</a>
+    </div>
+    {%- endif %}
+  </div>
+  <div class="right-details">
+
+    {# mod: replaced RTD icons with our links #}
+
+    {% if discourse %}
+    <div class="ask-discourse">
+      <a class="muted-link" href="{{ discourse }}">Ask a question on Discourse</a>
+    </div>
+    {% endif %}
+
+    {% if irc %}
+    <div class="ask-mattermost">
+      <a class="muted-link" href="{{ irc }}">Ask a question on IRC</a>
+    </div>
+    {% endif %}
+
+    {% if matrix %}
+    <div class="ask-matrix">
+      <a class="muted-link" href="{{ matrix }}">Ask a question on Matrix</a>
+    </div>
+    {% endif %}
+
+    {% if launchpad_url and launchpad_version and launchpad_folder %}
+
+    {% if launchpad_issues %}
+    <div class="issue-github">
+      <a class="muted-link" href="{{ launchpad_issues }}">Open a Launchpad issue for this documentation</a>
+    </div>
+    {% endif %}
+
+    <div class="edit-github">
+      <a class="muted-link" href="{{ launchpad_url }}/tree{{ launchpad_folder }}{{ pagename }}{{ page_source_suffix }}">View this page on Launchpad</a>
+    </div>
+    {% endif %}
+
+
+    </div>
+  </div>
+</div>
diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html
index 30c52c5..d0ac8e5 100644
--- a/docs/.sphinx/_templates/header.html
+++ b/docs/.sphinx/_templates/header.html
@@ -26,9 +26,9 @@
           </li>
           {% endif %}
 
-          {% if mattermost %}
+          {% if irc %}
           <li>
-            <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+            <a href="{{ irc }}" class="p-navigation__sub-link p-dropdown__link">IRC</a>
           </li>
           {% endif %}
 
@@ -38,9 +38,9 @@
           </li>
           {% endif %}
 
-          {% if github_url %}
+          {% if launchpad_url %}
           <li>
-            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+            <a href="{{ launchpad_url }}" class="p-navigation__sub-link p-dropdown__link">Launchpad</a>
           </li>
           {% endif %}
 
diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py
index 23d8901..cb73a64 100644
--- a/docs/.sphinx/get_vale_conf.py
+++ b/docs/.sphinx/get_vale_conf.py
@@ -3,16 +3,18 @@
 import requests
 import os
 
-DIR=os.getcwd()
+DIR = os.getcwd()
 
 def main():
-
     if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
         print("Vale directory exists")
     else:
         os.makedirs(f"{DIR}/.sphinx/styles/Canonical")
 
-    url = "https://api.github.com/repos/canonical/praecepta/contents/styles/Canonical"
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/Canonical"
+    )
     r = requests.get(url)
     for item in r.json():
         download = requests.get(item["download_url"])
@@ -20,22 +22,47 @@ def main():
         file.write(download.text)
         file.close()
 
+    # Update dictionary
+    if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"):
+        print("Dictionary directory exists")
+    else:
+        os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries")
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/config/dictionaries"
+    )
+    r = requests.get(url)
+    for item in r.json():
+        download = requests.get(item["download_url"])
+        file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w")
+        file.write(download.text)
+        file.close()
+
     if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"):
         print("Vocab directory exists")
     else:
         os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical")
-    
-    url = "https://api.github.com/repos/canonical/praecepta/contents/styles/config/vocabularies/Canonical"
+
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/config/vocabularies/Canonical"
+    )
     r = requests.get(url)
     for item in r.json():
         download = requests.get(item["download_url"])
-        file = open(".sphinx/styles/config/vocabularies/Canonical/" + item["name"], "w")
+        file = open(
+            ".sphinx/styles/config/vocabularies/Canonical/" + item["name"],
+            "w"
+        )
         file.write(download.text)
         file.close()
-    config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini")
+    config = requests.get(
+        "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini"
+    )
     file = open(".sphinx/vale.ini", "w")
     file.write(config.text)
     file.close()
 
+
 if __name__ == "__main__":
     main()
diff --git a/docs/.sphinx/metrics/build_metrics.sh b/docs/.sphinx/metrics/build_metrics.sh
new file mode 100755
index 0000000..bd1ff1c
--- /dev/null
+++ b/docs/.sphinx/metrics/build_metrics.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# shellcheck disable=all
+
+links=0
+images=0
+
+# count number of links
+links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<a " | wc -l)
+# count number of images
+images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<img " | wc -l)
+
+# summarise latest metrics
+echo "Summarising metrics for build files (.html)..."
+echo -e "\tlinks: $links"
+echo -e "\timages: $images"
diff --git a/docs/.sphinx/metrics/source_metrics.sh b/docs/.sphinx/metrics/source_metrics.sh
new file mode 100755
index 0000000..07147d6
--- /dev/null
+++ b/docs/.sphinx/metrics/source_metrics.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+# shellcheck disable=all
+
+VENV=".sphinx/venv/bin/activate"
+
+files=0
+words=0
+readabilityWords=0
+readabilitySentences=0
+readabilitySyllables=0
+readabilityAverage=0
+readable=true
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+    echo "There are no source files to calculate metrics"
+else
+    # measure raw total number of words, excluding those in .sphinx dir
+    words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+    # calculate readability for markdown source files
+    echo "Activating virtual environment to run vale..."
+    source "${VENV}"
+
+    for file in *.md *.rst; do
+        if [ -f "$file" ]; then
+            readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+            readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+            readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+        fi
+    done
+
+    echo "Deactivating virtual environment..."
+    deactivate
+
+    # calculate mean number of words
+    if [ "$files" -ge 1 ]; then
+        meanval=$((readabilityWords / files))
+    else
+        meanval=$readabilityWords
+    fi
+
+    readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
+
+    # cast average to int for comparison
+    readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
+
+    # value below 8 is considered readable
+    if [ "$readabilityAverageInt" -lt 8 ]; then
+        readable=true
+    else
+        readable=false
+    fi
+
+    # summarise latest metrics
+    echo "Summarising metrics for source files (.md, .rst)..."
+    echo -e "\ttotal files: $files"
+    echo -e "\ttotal words (raw): $words"
+    echo -e "\ttotal words (prose): $readabilityWords"
+    echo -e "\taverage word count: $meanval"
+    echo -e "\treadability: $readabilityAverage"
+    echo -e "\treadable: $readable"
+fi
diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json
index 8df0cb9..04dc1e1 100644
--- a/docs/.sphinx/pa11y.json
+++ b/docs/.sphinx/pa11y.json
@@ -6,4 +6,4 @@
   },
   "reporter": "cli",
   "standard": "WCAG2AA"
-}
\ No newline at end of file
+}
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
index c019f17..9ff666c 100644
--- a/docs/.sphinx/requirements.txt
+++ b/docs/.sphinx/requirements.txt
@@ -1,2 +1,4 @@
-git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx
+canonical-sphinx[full]
 sphinx-autobuild
+sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-last-updated-by-git
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
index 5f3dbad..9ee9ae7 100644
--- a/docs/.sphinx/spellingcheck.yaml
+++ b/docs/.sphinx/spellingcheck.yaml
@@ -1,30 +1,30 @@
 matrix:
-- name: rST files
-  aspell:
-    lang: en
-    d: en_GB
-  dictionary:
-    wordlists:
-    - .sphinx/.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
-      - a.contributor
+  - name: rST files
+    aspell:
+      lang: en
+      d: en_GB
+    dictionary:
+      wordlists:
+        - .sphinx/.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
+            - a.contributor
diff --git a/docs/Makefile b/docs/Makefile
index a861ba8..b9bdea0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,11 +1,23 @@
-# This Makefile stub allows you to customize starter pack (SP) targets.
-# Consider this file as a bridge between your project
-# and the starter pack's predefined targets that reside in Makefile.sp.
+# Minimal makefile for Sphinx documentation
 #
-# You can add your own, non-SP targets here or override SP targets
-# to fit your project's needs. For example, you can define and use targets
-# named "install" or "run", but continue to use SP targets like "sp-install"
-# or "sp-run" when working on the documentation.
+# Add your customisation to `Makefile` instead.
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXDIR       = .sphinx
+SPHINXOPTS      ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD     ?= $(VENVDIR)/bin/sphinx-build
+SOURCEDIR       = .
+BUILDDIR        = _build
+VENVDIR         = $(SPHINXDIR)/venv
+PA11Y           = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV         	   = $(VENVDIR)/bin/activate
+TARGET          = *
+ALLFILES        =  *.rst **/*.rst
+METRICSDIR      = $(SOURCEDIR)/.sphinx/metrics
+REQPDFPACKS     = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
+CONFIRM_SUDO    ?= N
+VALE_CONFIG     = $(SPHINXDIR)/vale.ini
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -23,8 +35,153 @@ help:
         "* check accessibility:                       make pa11y \n" \
         "* check style guide compliance:              make vale \n" \
         "* check style guide compliance on target:    make vale TARGET=* \n" \
+        "* check metrics for documentation:           make allmetrics \n" \
         "* other possible targets:                    make <TAB twice> \n" \
         "------------------------------------------------------------- \n"
 
+.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \
+        epub serve clean clean-doc spelling spellcheck linkcheck woke \
+        allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale
+
+full-help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+	@echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR):
+	python3 -c "import venv" || \
+        (echo "You must install python3-venv before you can build the documentation."; exit 1)
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR)
+	. $(VENV); pip install $(PIPOPTS) --require-virtualenv \
+	    --upgrade -r $(SPHINXDIR)/requirements.txt \
+            --log $(VENVDIR)/pip_install.log
+	@test ! -f $(VENVDIR)/pip_list.txt || \
+            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
+	@touch $(VENVDIR)
+
+spellcheck-install:
+	@type aspell >/dev/null 2>&1 || \
+	{ \
+		echo "Installing system-wide \"aspell\" packages..."; \
+		confirm_sudo=$(CONFIRM_SUDO); \
+		if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
+			read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
+		fi; \
+		if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
+			sudo apt-get install aspell aspell-en; \
+		else \
+			echo "Installation cancelled."; \
+		fi \
+	}
+
+pa11y-install:
+	@type $(PA11Y) >/dev/null 2>&1 || { \
+			echo "Installing \"pa11y\" from npm... \n"; \
+			mkdir -p $(SPHINXDIR)/node_modules/ ; \
+			npm install --prefix $(SPHINXDIR) pa11y; \
+		}
+
+install: $(VENVDIR)
+
+run: install
+	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf $(SPHINXDIR)/node_modules/
+	rm -rf $(SPHINXDIR)/styles
+	rm -rf $(VALE_CONFIG)
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+	rm -rf $(SPHINXDIR)/.doctrees
+
+spellcheck: spellcheck-install
+	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
+
+spelling: html spellcheck
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+	exit 0
+
+pa11y: pa11y-install html
+	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+
+vale-install: install
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@printf '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
+	@printf '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter
+	@printf '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+
+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
+	@printf "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@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
+	@printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@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
+	@printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) || true
+	@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
+	@for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
+        grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
+        (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \
+        echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
+        "Please be aware these packages will be installed to your system") && exit 1 ; done
+
+pdf-prep-force:
+	apt-get update
+	apt-get upgrade -y
+	apt-get install --no-install-recommends -y $(REQPDFPACKS) \
+
+pdf: pdf-prep
+	@. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@rm ./$(BUILDDIR)/latex/front-page-light.pdf || true
+	@rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true
+	@find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} +
+	@rm -r $(BUILDDIR)/latex
+	@echo "\nOutput can be found in ./$(BUILDDIR)\n"
+
+allmetrics: html
+	@echo "Recording documentation metrics..."
+	@echo "Checking for existence of vale..."
+	. $(VENV)
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+	@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
+	@eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)'
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	$(MAKE) -f Makefile.sp sp-$@
+	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/Makefile.sp b/docs/Makefile.sp
deleted file mode 100644
index 80b5141..0000000
--- a/docs/Makefile.sp
+++ /dev/null
@@ -1,114 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-# `Makefile.sp` is from the Sphinx starter pack and should not be
-# modified.
-# Add your customisation to `Makefile` instead.
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXDIR     = .sphinx
-SPHINXOPTS    ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
-SPHINXBUILD   ?= $(VENVDIR)/bin/sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-VENVDIR       = $(SPHINXDIR)/venv
-PA11Y         = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
-VENV          = $(VENVDIR)/bin/activate
-TARGET        = *
-ALLFILES      =  *.rst **/*.rst
-
-.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \
-        sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
-        sp-pa11y Makefile.sp sp-vale
-
-sp-full-help: $(VENVDIR)
-	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
-	@echo "Run 'make help' to see supported targets."
-
-# If requirements are updated, venv should be rebuilt and timestamped.
-$(VENVDIR):
-	python3 -c "import venv" || \
-        (echo "You must install python3-venv before you can build the documentation."; exit 1)
-	@echo "... setting up virtualenv"
-	python3 -m venv $(VENVDIR)
-	. $(VENV); pip install --require-virtualenv \
-	    --upgrade -r $(SPHINXDIR)/requirements.txt \
-            --log $(VENVDIR)/pip_install.log
-	@test ! -f $(VENVDIR)/pip_list.txt || \
-            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
-	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
-	@touch $(VENVDIR)
-
-sp-woke-install:
-	@type woke >/dev/null 2>&1 || \
-            { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
-
-sp-spellcheck-install:
-	@type aspell >/dev/null 2>&1 || \
-            { echo "Installing aspell... \n"; sudo apt-get install aspell aspell-en; }
-
-sp-pa11y-install:
-	@type $(PA11Y) >/dev/null 2>&1 || { \
-			echo "Installing \"pa11y\" from npm... \n"; \
-			mkdir -p $(SPHINXDIR)/node_modules/ ; \
-			npm install --prefix $(SPHINXDIR) pa11y; \
-		}
-
-sp-install: $(VENVDIR)
-
-sp-run: sp-install
-	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
-
-# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
-sp-html: sp-install
-	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-epub: sp-install
-	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-serve: sp-html
-	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
-
-sp-clean: sp-clean-doc
-	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
-	rm -rf $(VENVDIR)
-	rm -rf $(SPHINXDIR)/node_modules/
-	rm -rf $(SPHINXDIR)/styles
-	rm -rf $(SPHINXDIR)/vale.ini
-
-sp-clean-doc:
-	git clean -fx "$(BUILDDIR)"
-	rm -rf $(SPHINXDIR)/.doctrees
-
-sp-spellcheck: sp-spellcheck-install
-	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
-
-sp-spelling: sp-html sp-spellcheck
-
-sp-linkcheck: sp-install
-	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
-	exit 0
-
-sp-woke: sp-woke-install
-	woke $(ALLFILES) --exit-1-on-failure \
-	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
-
-sp-pa11y: sp-pa11y-install sp-html
-	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
-
-sp-vale: sp-install
-	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
-	@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
-	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
-	@echo ""
-	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
-	@echo ""
-	@. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET)
-
-
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sp
-	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
index a8b1cd9..c8e6449 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -82,37 +82,24 @@ html_context = {
     # (use an empty value if you don't want to link)
     'discourse': 'https://discourse.ubuntu.com',
 
-    # Change to the Mattermost channel you want to link to
-    # (use an empty value if you don't want to link)
-    'mattermost': '',
-
-    # Change to the Matrix channel you want to link to
-    # (use an empty value if you don't want to link)
-    'matrix': '',
-
-    # Change to the GitHub URL for your project
-    # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
-    'github_url': 'https://launchpad.net/~techboard/ubuntu-governance-docs',
-
+    # Your IRC channel
+    "irc": "https://web.libera.chat/gamja/?channels=%23ubuntu-devel",
+    # Your Matrix channel URL
+    "matrix": "https://matrix.to/#/#devel:ubuntu.com",
+    # Your Launchpad URL
+    "launchpad_url": "https://git.launchpad.net/ubuntu-governance-docs",
     # Change to the branch for this version of the documentation
-    'github_version': 'main',
-
+    "launchpad_version": "main",
     # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    'github_folder': '/docs/',
-
-    # Change to an empty value if your GitHub repo doesn't have issues enabled.
-    # This will disable the feedback button and the issue link in the footer.
-    'github_issues': '',
-
+    "launchpad_folder": "/docs/",
+    # Change to an empty value to disable the issue link in the footer.
+    "launchpad_issues": "https://bugs.launchpad.net/ubuntu-governance-docs/+filebug",
     # Controls the existence of Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
-    # 'sequential_nav': "none",
-
-    # Uncomment to disable displaying the contributors for each file.
-    # (You can also limit the time frame for displaying contributors
-    # by setting a "display_contributors_since" variable.)
-    # "display_contributors": False,
+    "sequential_nav": "both",
+    # Controls whether to display the contributors for each file
+    "display_contributors": False,
 
 }
 
@@ -178,12 +165,13 @@ myst_enable_extensions = {
 # If you need more extensions, add them here (in addition to
 # canonical_sphinx).
 extensions = [
-    'canonical_sphinx'
+    "canonical_sphinx",
+    "sphinxcontrib.cairosvgconverter",
+    "sphinx_last_updated_by_git",
     ]
 
 # Add files or directories that should be excluded from processing.
 exclude_patterns = [
-    'doc-cheat-sheet*',
     ]
 
 # Add custom CSS files (located in .sphinx/_static/)