From 9af734530903c4306e81d5e86d2d459b9efdd34b Mon Sep 17 00:00:00 2001
From: Teodora Mihoc <teodora.mihoc@canonical.com>
Date: Mon, 8 Dec 2025 17:47:10 +0100
Subject: [PATCH 1/5] docs: upgrade starter pack using gemini

---
 .sphinx/get_vale_conf.py          |  16 +-
 .sphinx/metrics/build_metrics.py  |  94 +++++++++
 .sphinx/metrics/source_metrics.sh |  66 +++++++
 .sphinx/update_sp.py              |   8 +-
 .sphinx/version                   |   2 +-
 Makefile                          |  42 ++--
 conf.py                           |  81 ++++----
 requirements.txt                  |  33 +++-
 reuse/links.txt                   |  11 +-
 reuse/mermaid.txt                 | 313 ++++++++++++++++++++++++++++++
 reuse/substitutions.yaml          |   2 +-
 upgrade_prompt.md                 |  69 +++++++
 upgrade_report.md                 |  22 +++
 13 files changed, 683 insertions(+), 76 deletions(-)
 create mode 100755 .sphinx/metrics/build_metrics.py
 create mode 100755 .sphinx/metrics/source_metrics.sh
 create mode 100644 reuse/mermaid.txt
 create mode 100644 upgrade_prompt.md
 create mode 100644 upgrade_report.md

diff --git a/.sphinx/get_vale_conf.py b/.sphinx/get_vale_conf.py
index e2a81c0..13e7966 100644
--- a/.sphinx/get_vale_conf.py
+++ b/.sphinx/get_vale_conf.py
@@ -31,12 +31,12 @@
 def clone_repo_and_copy_paths(file_source_dest, overwrite=False):
     """
     Clone the repository to a temporary directory and copy required files
-    
+
     Args:
         file_source_dest: dictionary of file paths to copy from the repository,
             and their destination paths
         overwrite: boolean flag to overwrite existing files in the destination
-    
+
     Returns:
         bool: True if all files were copied successfully, False otherwise
     """
@@ -52,8 +52,8 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False):
 
     try:
         result = subprocess.run(
-            clone_cmd, 
-            capture_output=True, 
+            clone_cmd,
+            capture_output=True,
             text=True,
             check=True
         )
@@ -73,7 +73,7 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False):
             continue
 
         if not copy_files_to_path(source_path, dest, overwrite):
-            is_copy_success = False            
+            is_copy_success = False
             logging.error("Failed to copy %s to %s", source_path, dest)
 
     # Clean up temporary directory
@@ -85,12 +85,12 @@ def clone_repo_and_copy_paths(file_source_dest, overwrite=False):
 def copy_files_to_path(source_path, dest_path, overwrite=False):
     """
     Copy a file or directory from source to destination
-    
+
     Args:
         source_path: Path to the source file or directory
         dest_path: Path to the destination
         overwrite: Boolean flag to overwrite existing files in the destination
-        
+
     Returns:
         bool: True if copy was successful, False otherwise
     """
@@ -138,7 +138,7 @@ def main():
     # Parse command line arguments, default to overwrite_enabled = True
     overwrite_enabled = not parse_arguments().no_overwrite
 
-    # Download into /tmp through git clone 
+    # Download into /tmp through git clone
     if not clone_repo_and_copy_paths(vale_files_dict, overwrite=overwrite_enabled):
         logging.error("Failed to download files from repository")
         return 1
diff --git a/.sphinx/metrics/build_metrics.py b/.sphinx/metrics/build_metrics.py
new file mode 100755
index 0000000..529fb85
--- /dev/null
+++ b/.sphinx/metrics/build_metrics.py
@@ -0,0 +1,94 @@
+#!/usr/bin/python3
+
+import sys
+import argparse
+from pathlib import Path
+from html.parser import HTMLParser
+from urllib.parse import urlsplit
+
+
+class MetricsParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.int_link_count = 0
+        self.ext_link_count = 0
+        self.fragment_count = 0
+        self.image_count = 0
+        self.in_object = 0
+
+    @property
+    def link_count(self):
+        return self.fragment_count + self.int_link_count + self.ext_link_count
+
+    def read(self, file):
+        """
+        Read *file* (a file-like object with a ``read`` method returning
+        strings) a chunk at a time, feeding each chunk to the parser.
+        """
+        # Ensure the parser state is reset before each file (just in case
+        # there's an erroneous dangling <object>)
+        self.reset()
+        self.in_object = 0
+        buf = ''
+        while True:
+            # Parse 1MB chunks at a time
+            buf = file.read(1024**2)
+            if not buf:
+                break
+            self.feed(buf)
+
+    def handle_starttag(self, tag, attrs):
+        """
+        Count <a>, <img>, and <object> tags to determine the number of internal
+        and external links, and the number of images.
+        """
+        attrs = dict(attrs)
+        if tag == 'a' and 'href' in attrs:
+            # If there's no href, it's an anchor; if there's no hostname
+            # (netloc) or path, it's just a fragment link within the page
+            url = urlsplit(attrs['href'])
+            if url.netloc:
+                self.ext_link_count += 1
+            elif url.path:
+                self.int_link_count += 1
+            else:
+                self.fragment_count += 1
+        elif tag == 'object':
+            # <object> tags are a bit complex as they nest to offer fallbacks
+            # and may contain an <img> fallback. We only want to count the
+            # outer-most <object> in this case
+            if self.in_object == 0:
+                self.image_count += 1
+            self.in_object += 1
+        elif tag == 'img' and self.in_object == 0:
+            self.image_count += 1
+
+    def handle_endtag(self, tag):
+        if tag == 'object':
+            # Never let in_object be negative
+            self.in_object = max(0, self.in_object - 1)
+
+
+def main(args=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        'build_dir', metavar='build-dir', nargs='?', default='.',
+        help="The directory to scan for HTML files")
+    config = parser.parse_args(args)
+
+    parser = MetricsParser()
+    for path in Path(config.build_dir).rglob('*.html'):
+        with path.open('r', encoding='utf-8', errors='replace') as f:
+            parser.read(f)
+
+    print('Summarising metrics for build files (.html)...')
+    print(f'\tlinks: {parser.link_count} ('
+          f'{parser.fragment_count} #frag…, '
+          f'{parser.int_link_count} /int…, '
+          f'{parser.ext_link_count} https://ext…'
+          ')')
+    print(f'\timages: {parser.image_count}')
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/.sphinx/metrics/source_metrics.sh b/.sphinx/metrics/source_metrics.sh
new file mode 100755
index 0000000..07147d6
--- /dev/null
+++ b/.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/.sphinx/update_sp.py b/.sphinx/update_sp.py
index 1d6afd5..576cfcd 100755
--- a/.sphinx/update_sp.py
+++ b/.sphinx/update_sp.py
@@ -18,7 +18,9 @@
 from requests.exceptions import RequestException
 from packaging.version import parse as parse_version
 
-SPHINX_DIR = os.path.join(os.getcwd(), ".sphinx")
+SPHINX_DIR = os.path.abspath(os.path.dirname(__file__))
+DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, '..'))
+REQUIREMENTS = os.path.join(DOCS_DIR, "requirements.txt")
 SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update")
 GITHUB_REPO = "canonical/sphinx-docs-starter-pack"
 GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}"
@@ -103,7 +105,7 @@ def main():
     # Check requirements are the same
     new_requirements = []
     try:
-        with open("requirements.txt", "r") as file:
+        with open(REQUIREMENTS, "r") as file:
             logging.debug("Checking requirements")
 
             local_reqs = set(file.read().splitlines()) - {""}
@@ -206,7 +208,7 @@ def update_static_files():
     # Writes return value for parent function
     if new_file_list != []:
         # Provides more information on new files
-        with open("NEWFILES.txt", "w") as f:
+        with open(f"{SPHINX_DIR}/NEWFILES.txt", "w") as f:
             for entry in new_file_list:
                 f.write(f"{entry}\n")
         logging.debug("Some downloaded files are new")
diff --git a/.sphinx/version b/.sphinx/version
index 26aaba0..f0bb29e 100644
--- a/.sphinx/version
+++ b/.sphinx/version
@@ -1 +1 @@
-1.2.0
+1.3.0
diff --git a/Makefile b/Makefile
index 9640e5e..de174a9 100644
--- a/Makefile
+++ b/Makefile
@@ -13,11 +13,12 @@ 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
+VALEDIR         = $(SPHINXDIR)/venv/lib/python*/site-packages/vale
+VOCAB_CANONICAL = $(SPHINXDIR)/styles/config/vocabularies/Canonical
 SPHINX_HOST     ?= 127.0.0.1
 SPHINX_PORT     ?= 8000
 
@@ -78,21 +79,17 @@ pymarkdownlnt-install:
 install: $(VENVDIR)
 
 run: install
-	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) \
-		--ignore "$(VENVDIR)/**" \
-		--ignore "$(SPHINXDIR)/**" \
-		--ignore "$(BUILDDIR)/**" \
-		"$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 # Does not 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)
+	. $(VENV); $(SPHINXBUILD) --fail-on-warning --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
+	cd "$(BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT)
 
 clean: clean-doc
 	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
@@ -116,33 +113,32 @@ lint-md: pymarkdownlnt-install
 	@. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=./$(SPHINXDIR)/** $(SOURCEDIR)
 
 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
 	@echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
 	@echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter
 	@echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter
-	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --version \;
+	@. $(VENV); find $(VALEDIR)/vale_bin -size 195c -exec vale --version \;
 
 woke: vale-install
-	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
-	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@cat $(VOCAB_CANONICAL)/accept.txt > $(VOCAB_CANONICAL)/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(VOCAB_CANONICAL)/accept.txt
 	@echo "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command"
 	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET)
-	@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
+	@cat $(VOCAB_CANONICAL)/accept_backup.txt > $(VOCAB_CANONICAL)/accept.txt && rm $(VOCAB_CANONICAL)/accept_backup.txt
 
 vale: vale-install
-	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
-	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@cat $(VOCAB_CANONICAL)/accept.txt > $(VOCAB_CANONICAL)/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(VOCAB_CANONICAL)/accept.txt
 	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
 	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET)
-	@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
+	@cat $(VOCAB_CANONICAL)/accept_backup.txt > $(VOCAB_CANONICAL)/accept.txt && rm $(VOCAB_CANONICAL)/accept_backup.txt
 
 spelling: vale-install
-	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
-	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@cat $(VOCAB_CANONICAL)/accept.txt > $(VOCAB_CANONICAL)/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(VOCAB_CANONICAL)/accept.txt
 	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
 	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET)
-	@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
+	@cat $(VOCAB_CANONICAL)/accept_backup.txt > $(VOCAB_CANONICAL)/accept.txt && rm $(VOCAB_CANONICAL)/accept_backup.txt
 
 spellcheck: spelling
 	@echo "Please note that the \`make spellcheck\` command is being deprecated in favor of \`make spelling\`"
@@ -173,11 +169,11 @@ 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 -d $(VALEDIR) || 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 \;
+	@. $(VENV); find $(VALEDIR)/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
 	@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
-	@$(METRICSDIR)/build_metrics.py $(BUILDDIR)
+	@. $(VENV); python3 $(METRICSDIR)/build_metrics.py $(BUILDDIR)
 
 update: install
 	@. $(VENV); .sphinx/update_sp.py
@@ -185,5 +181,5 @@ update: install
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	$(MAKE) —no-print-directory install
+	$(MAKE) --no-print-directory install
 	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/conf.py b/conf.py
index 6c07269..19aa247 100644
--- a/conf.py
+++ b/conf.py
@@ -1,5 +1,4 @@
 import datetime
-import ast
 import os
 import yaml
 
@@ -29,7 +28,6 @@
 author = 'Canonical Group Ltd'
 
 
-
 # Sidebar documentation title; best kept reasonably short
 #
 # TODO: To include a version number, add it here (hardcoded or automated).
@@ -144,11 +142,6 @@
 slug = 'jaas'
 
 
-# Template and asset locations
-
-html_static_path = [".sphinx/_static"]
-templates_path = [".sphinx/_templates"]
-
 #######################
 # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
 #######################
@@ -168,6 +161,25 @@
 
 sitemap_show_lastmod = True
 
+# Exclude generated pages from the sitemap:
+
+sitemap_excludes = [
+    '404/',
+    'genindex/',
+    'search/',
+]
+
+# TODO: Add more pages to sitemap_excludes if needed. Wildcards are supported.
+#       For example, to exclude module pages generated by autodoc, add '_modules/*'.
+
+#######################
+# Template and asset locations
+#######################
+
+html_static_path = [".sphinx/_static"]
+templates_path = [".sphinx/_templates"]
+
+
 #############
 # Redirects #
 #############
@@ -188,6 +200,7 @@
 "reference/service-account": "https://canonical-terraform-provider-juju.readthedocs-hosted.com/latest/howto/manage-service-accounts/",
 }
 
+
 ###########################
 # Link checker exceptions #
 ###########################
@@ -206,8 +219,10 @@
     "https://www.vaultproject.io/*"
     ]
 
+
 # A regex list of URLs where anchors are ignored by 'make linkcheck'
-# linkcheck_anchors_ignore_for_url = [r"https://github.com/.*"]
+
+linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"]
 
 # give linkcheck multiple tries on failure
 # linkcheck_timeout = 30
@@ -230,37 +245,31 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 
 # NOTE: The canonical_sphinx extension is required for the starter pack.
-#       It automatically enables the following extensions:
-#       - custom-rst-roles
-#       - myst_parser
-#       - notfound.extension
-#       - related-links
-#       - sphinx_copybutton
-#       - sphinx_design
-#       - sphinx_reredirects
-#       - sphinx_tabs.tabs
-#       - sphinxcontrib.jquery
-#       - sphinxext.opengraph
-#       - terminal-output
-#       - youtube-links
 
 extensions = [
     "canonical_sphinx",
+    "notfound.extension",
+    "sphinx_design",
+    "sphinx_reredirects",
+    "sphinx_tabs.tabs",
+    "sphinxcontrib.jquery",
+    "sphinxext.opengraph",
+    "sphinx_config_options",
+    "sphinx_contributor_listing",
+    "sphinx_filtered_toctree",
+    "sphinx_related_links",
+    "sphinx_roles",
+    "sphinx_terminal",
+    "sphinx_ubuntu_images",
+    "sphinx_youtube_links",
     "sphinxcontrib.cairosvgconverter",
     "sphinx_last_updated_by_git",
-    # further extensions that jaas already had:
-    # 'sphinx_copybutton',
-    # 'sphinxcontrib.jquery'
-    # further extensions that we also enable in juju:
-    # Make it possible to link to related RTD projects using their internal anchors
-    # with, e.g., {external+ops:ref}`manage-configurations`:
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.intersphinx",
+    "sphinx_sitemap",
+    # Project specific extensions
     'sphinxext.rediraffe',
-    # Display an external link icon and open link in new tab:
-    # new_tab_link_show_external_link_icon must also be set to True
     'sphinx_new_tab_link',
     'sphinxcontrib.lightbox2',
-    'sphinx_sitemap',
 ]
 
 new_tab_link_show_external_link_icon = True
@@ -271,18 +280,24 @@
   'CONTRIBUTING.md',
   'TODO.md',
   'README.md',
+  'sp-updated',
+  'upgrade_prompt.md',
 ]
 
-# Add CSS files (located in .sphinx/_static/)
+# Adds custom CSS files, located under 'html_static_path'
+
 html_css_files = [
 	'css/cookie-banner.css'
 ]
 
-# Add JavaScript files (located in .sphinx/_static/)
+
+# Adds custom JavaScript files, located under 'html_static_path'
+
 html_js_files = [
 	'js/bundle.js',
 ]
 
+
 # Specifies a reST snippet to be appended to each .rst file
 
 rst_epilog = """
diff --git a/requirements.txt b/requirements.txt
index 79f7568..b98b481 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,10 +1,37 @@
-canonical-sphinx[full]
-packaging    
+# Canonical theme (still needed for Furo theme and custom templates)
+canonical-sphinx>=0.5.1
+
+# Extensions previously auto-loaded by canonical-sphinx
+myst-parser
+sphinx-autobuild
+sphinx-design
+sphinx-notfound-page
+sphinx-reredirects
+sphinx-tabs
+sphinxcontrib-jquery
+sphinxext-opengraph
+
+# Extra extensions, previously bundled as canonical-sphinx-extensions
+sphinx-config-options>=0.1.0
+sphinx-contributor-listing>=0.1.0
+sphinx-filtered-toctree>=0.1.0
+sphinx-related-links>=0.1.1
+sphinx-roles>=0.1.0
+sphinx-terminal>=1.0.2
+sphinx-ubuntu-images>=0.1.0
+sphinx-youtube-links>=0.1.0
+
+# Other dependencies
+packaging
 sphinxcontrib-svg2pdfconverter[CairoSVG]
 sphinx-last-updated-by-git
 sphinx-sitemap
+
+# Vale dependencies
+rst2html
+vale
+
 # specific to this project:
 sphinxext-rediraffe
 sphinx-new-tab-link
 sphinxcontrib.lightbox2
-    
diff --git a/reuse/links.txt b/reuse/links.txt
index 0ac9bfb..af3c3b5 100644
--- a/reuse/links.txt
+++ b/reuse/links.txt
@@ -2,16 +2,18 @@
 .. _Canonical Reference Library: https://library.canonical.com/
 .. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx
 .. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log
+.. _csv-table reference: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
+.. _csv-table reference (MyST): https://mystmd.org/guide/directives#directive-csv-table
 .. _Diátaxis: https://diataxis.fr/
 .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
 .. _Example product documentation repository: https://github.com/canonical/example-product-documentation
 .. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
-.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/news-blogs/five-golden-rules-compliant-alt-text
+.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text
 .. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/
 .. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
 .. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/
 .. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html
-.. _How to manually configure a Git repository integration: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html
+.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html
 .. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
 .. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance
 .. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
@@ -26,16 +28,17 @@
 .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 .. _`Sphinx`: https://www.sphinx-doc.org/
 .. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html
+.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/
 .. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/
 .. _Sphinx documentation starter pack:
-.. _Sphinx documentation starter pack repository: https://github.com/canonical/starter-pack
+.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack
 .. _Sphinx documentation starter pack documentation: https://canonical-starter-pack.readthedocs-hosted.com/
 .. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 .. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/
 .. _tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives
 .. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
 .. _Vale: https://vale.sh/
-.. _Vale rules: https://github.com/canonical/praecepta
+.. _Vale rules: https://github.com/canonical/documentation-style-guide
 .. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/
 
 
diff --git a/reuse/mermaid.txt b/reuse/mermaid.txt
new file mode 100644
index 0000000..68ec1b5
--- /dev/null
+++ b/reuse/mermaid.txt
@@ -0,0 +1,313 @@
+mermaid-diagram-flowchart-start
+``````{tab-set}
+
+`````{tab-item} Diagram
+```{image} https://assets.ubuntu.com/v1/34c7105c-screenshot_from_2025_10_13_15_05_56.png
+```
+`````
+
+`````{tab-item} MyST
+
+````{code-block} md
+```{mermaid}
+flowchart LR
+    A([New PR])
+    B[Needs review]
+    C{Review approved?}
+    D{Merge conflicts?}
+    E[Needs work]
+    F[Needs CI]
+    G{Passed testing?}
+    H[Ready for merge]
+    I[(PR merged)]
+    J{Comments addressed?}
+    K[(PR closed)]
+
+    A --> B
+    B --> C
+    C -- no --> E
+    C -- yes --> D
+    D -- yes --> E
+    D -- no --> F
+    F --> G
+    G -- yes --> H
+    G -- no --> E
+    H --> I
+    E --> J
+    J -- yes --> B
+    J -- no --> K
+```
+````
+
+`````
+
+`````{tab-item} rST
+
+````{code-block} rst
+.. mermaid::
+
+   flowchart LR
+       A([New PR])
+       B[Needs review]
+       C{Review approved?}
+       D{Merge conflicts?}
+       E[Needs work]
+       F[Needs CI]
+       G{Passed testing?}
+       H[Ready for merge]
+       I[(PR merged)]
+       J{Comments addressed?}
+       K[(PR closed)]
+   
+       A --> B
+       B --> C
+       C -- no --> E
+       C -- yes --> D
+       D -- yes --> E
+       D -- no --> F
+       F --> G
+       G -- yes --> H
+       G -- no --> E
+       H --> I
+       E --> J
+       J -- yes --> B
+       J -- no --> K
+````
+
+`````
+``````
+mermaid-diagram-flowchart-end
+
+mermaid-diagram-sequence-start
+``````{tab-set}
+
+`````{tab-item} Diagram
+
+```{image} https://assets.ubuntu.com/v1/a7eb0fcf-screenshot_from_2025_10_13_15_08_06.png
+```
+
+`````
+
+`````{tab-item} Custom CSS
+
+First, create a Mermaid stylesheet in the {file}`_static` directory and
+customize it as needed. For example, {file}`mermaid-sequence.css`.
+
+Then, enable custom stylesheets in {file}`conf.py`.
+Uncomment this line so Sphinx can use local stylesheets:
+
+```{code-block} py
+:caption: conf\.py
+
+html_static_path = ["_static"]
+```
+
+Link to your custom Mermaid stylesheet:
+
+```{code-block} py
+:caption: conf\.py
+
+html_css_files = [
+    "mermaid-sequence.css",
+]
+```
+
+Here's an example stylesheet that changes the default typefaces and colors of Mermaid components.
+It also sets a solid background color for all Mermaid diagrams.
+
+```{code-block} css
+:caption: mermaid-sequence.css
+
+.actor {
+  stroke: #eb6536 !important;
+  stroke-width: 2;
+  fill: #f5b29b !important;
+}
+
+text.actor {
+  fill: black;
+  stroke: none;
+  font-family: Helvetica;
+}
+
+.actor-line {
+  stroke: #77216f;
+}
+
+.mermaid {
+    background-color: #f0f0f0;
+    border: 1px solid #ccc;
+    border-radius: 6px;
+    padding: 0.5em;
+}
+```
+`````
+
+`````{tab-item} MyST
+
+````{code-block} md
+```{mermaid}
+sequenceDiagram
+    participant User
+    participant Snap as snapd (Client)
+    participant Store as Snap Store
+    participant System
+
+    User->>Snap: snap install hello
+    Snap->>Store: Request snap info and download
+    Store-->>Snap: Return snap package
+    Snap->>System: Install and mount snap
+    System-->>Snap: Installation result
+    Snap-->>User: Confirm snap is installed
+```
+````
+
+`````
+
+`````{tab-item} rST
+
+````{code-block} rst
+.. mermaid::
+
+   sequenceDiagram
+       participant User
+       participant Snap as snapd (Client)
+       participant Store as Snap Store
+       participant System
+   
+       User->>Snap: snap install hello
+       Snap->>Store: Request snap info and download
+       Store-->>Snap: Return snap package
+       Snap->>System: Install and mount snap
+       System-->>Snap: Installation result
+       Snap-->>User: Confirm snap is installed
+````
+
+`````
+``````
+mermaid-diagram-sequence-end
+
+mermaid-diagram-timeline-start
+``````{tab-set}
+
+`````{tab-item} Diagram
+
+```{image} https://assets.ubuntu.com/v1/24895eed-screenshot_from_2025_10_13_15_06_35.png
+```
+
+`````
+
+`````{tab-item} MyST
+
+````{code-block} md
+:emphasize-lines: 2
+```{mermaid}
+%%{init: {"theme":"forest"}}%%
+timeline
+    title Ubuntu recent releases
+
+    2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
+    2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
+    2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
+    2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
+    2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
+    2025 : 25.04 (Plucky Puffin)
+```
+````
+
+`````
+
+`````{tab-item} rST
+
+````{code-block} rst
+:emphasize-lines: 3
+
+.. mermaid::
+
+   %%{init: {"theme":"forest"}}%%
+   timeline
+       title Ubuntu recent releases
+
+       2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
+       2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
+       2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
+       2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
+       2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
+       2025 : 25.04 (Plucky Puffin)
+````
+
+`````
+``````
+mermaid-diagram-timeline-end
+
+mermaid-diagram-state-start
+``````{tab-set}
+
+`````{tab-item} Diagram
+
+```{image} https://assets.ubuntu.com/v1/dd4fb237-screenshot_from_2025_10_13_15_08_51.png
+```
+
+`````
+
+`````{tab-item} MyST
+
+````{code-block} md
+:emphasize-lines: 3-6, 17-20
+
+```{mermaid}
+stateDiagram-v2
+    classDef review fill:#FCE83A
+    classDef approved  fill:#2DCCFF
+    classDef published fill:#56F000
+    classDef archived fill:#7B8089
+
+    [*] --> Draft
+    Draft --> Review : submit for review
+    Review --> Draft : changes requested
+    Review --> Approved : review passed
+    Approved --> Build : trigger build
+    Build --> Published : build success
+    Build --> Draft : build failed
+    Published --> Archived : old version
+
+    class Review review
+    class Approved approved
+    class Published published
+    class Archived archived
+```
+````
+
+`````
+
+`````{tab-item} rST
+
+````{code-block} rst
+:emphasize-lines: 4-7, 18-21
+
+.. mermaid::
+
+    stateDiagram-v2
+        classDef review fill:#FCE83A
+        classDef approved  fill:#2DCCFF
+        classDef published fill:#56F000
+        classDef archived fill:#7B8089
+    
+        [*] --> Draft
+        Draft --> Review : submit for review
+        Review --> Draft : changes requested
+        Review --> Approved : review passed
+        Approved --> Build : trigger build
+        Build --> Published : build success
+        Build --> Draft : build failed
+        Published --> Archived : old version
+    
+        class Review review
+        class Approved approved
+        class Published published
+        class Archived archived
+````
+
+`````
+``````
+mermaid-diagram-state-end
\ No newline at end of file
diff --git a/reuse/substitutions.yaml b/reuse/substitutions.yaml
index be8526d..0c2958d 100644
--- a/reuse/substitutions.yaml
+++ b/reuse/substitutions.yaml
@@ -1,4 +1,4 @@
 # Key/value substitutions to use within the Sphinx doc.
 {version_number: "0.1.0",
  formatted_text: "*Multi-line* text\n that uses basic **markup**.",
- site_link: "[Website link](https://example.com)"}
+ site_link: "[Website link](https://example.com)"}
\ No newline at end of file
diff --git a/upgrade_prompt.md b/upgrade_prompt.md
new file mode 100644
index 0000000..966e7f1
--- /dev/null
+++ b/upgrade_prompt.md
@@ -0,0 +1,69 @@
+Title: In-Place Upgrade of Canonical Sphinx Starter Pack with Breaking Change Mitigation
+
+Mission:
+Perform a robust, in-place upgrade of an existing Sphinx documentation project (`docs/`) to a newer Canonical starter pack version (`sp-updated/`). The upgrade must preserve local customizations while proactively identifying and resolving breaking changes in dependencies, configuration, and directive syntax (e.g., deprecated options in MyST or Sphinx extensions).
+
+Context:
+- `docs/`: Existing documentation project with customizations (conf.py, extensions, themes).
+- `sp-updated/`: New starter pack reference implementation.
+- Common pitfalls in this upgrade path include:
+  - "Unbundling" of extensions (extensions previously included in a meta-package must now be listed explicitly).
+  - Syntax changes in directives (e.g., `sphinx-terminal` changing how inputs are defined).
+  - Build failures due to stricter warning policies in newer Makefiles.
+
+Task Requirements:
+1. **Mandatory Backup**: Create a full backup of `docs/` before applying changes.
+2. **Dependency Reconciliation**: Explicitly check if the new starter pack requires listing extensions that were previously implicit.
+3. **Syntax Migration**: Proactively scan for and migrate deprecated directive syntax by comparing existing usage against new starter pack examples.
+4. **Robust Tooling**: Use Python scripts for complex multi-line text replacements or migrations, rather than fragile shell one-liners (sed/awk).
+5. **Clean Build**: Ensure `make html` passes with zero warnings.
+
+Process / Steps:
+1. **Initial Assessment & Backup**:
+   - Identify project root, `docs/`, and `sp-updated/`.
+   - **CRITICAL**: Create a recursive backup of `docs/` (e.g., `cp -r docs docs_backup`).
+   - List active extensions in `docs/conf.py` and dependencies in `docs/requirements.txt`.
+
+2. **Dependency & Configuration Analysis**:
+   - Compare `sp-updated/docs/requirements.txt` with `docs/requirements.txt`.
+   - **Crucial Check**: If `canonical-sphinx` is updated, check if it has "unbundled" extensions. You will likely need to explicitly add packages like `sphinx-design`, `sphinx-copybutton`, `sphinx-terminal`, etc., to `docs/requirements.txt` and `docs/conf.py` even if they weren't there before.
+   - Create a new `docs/conf.py` by merging:
+     - The *new* structure and defaults from `sp-updated/`.
+     - The *existing* project metadata (`project`, `copyright`, `html_context`, `html_theme_options`) and custom extensions from the old `conf.py`.
+
+3. **Structure Synchronization**:
+   - Update `docs/Makefile` to the new version.
+   - Copy new or updated assets from `sp-updated/docs/reuse/` to `docs/reuse/`.
+   - Update `_static` and `_templates` only if they don't contain project-specific overrides.
+
+4. **Syntax Compatibility Scan**:
+   - Before building, compare the usage of key directives (e.g., `{terminal}`, `{tabs}`, `{note}`) in `docs/` against the reference examples in `sp-updated/docs/reference/`.
+   - **Action**: If syntax has changed (e.g., `:input:` option deprecated in favor of body content), write a Python script to automate the migration across all `.md` and `.rst` files. Do not rely on manual edits or simple regex for structural changes.
+
+5. **Iterative Build & Fix**:
+   - Run `make html` in `docs/`.
+   - **Phase 1 - Dependencies**: Fix `ModuleNotFoundError` by adding missing packages to `requirements.txt`.
+   - **Phase 2 - Configuration**: Fix configuration errors in `conf.py`.
+   - **Phase 3 - Syntax/Content**: Fix warnings (treated as errors) related to directive usage. Use the Python script approach for batch fixes.
+
+6. **Validation**:
+   - Verify the build completes successfully.
+   - Manually inspect generated HTML for complex directives (terminals, tabs) to ensure they render correctly.
+   - Ensure custom extensions (e.g., Mermaid, specific roles) still function.
+
+7. **Cleanup & Reporting**:
+   - Remove `docs_backup`, `sp-updated/`, and any temporary migration scripts.
+   - Generate a report (`upgrade_report.md`) detailing:
+     - Configuration changes.
+     - Dependency updates (specifically unbundled extensions).
+     - Syntax migrations performed (e.g., "Converted terminal directive from :input: style to body style").
+
+Constraints & Guardrails:
+- **Never** overwrite `conf.py` blindly; always merge.
+- **Never** leave the repository in a broken build state.
+- **Prefer** Python scripts for migration logic to ensure handling of newlines and indentation is correct.
+- **Maintain** the `docs/` directory as the source of truth; do not switch to `sp-updated/`.
+
+Output Specification:
+- Produce the final upgraded `docs/` directory.
+- Produce `upgrade_report.md`.
diff --git a/upgrade_report.md b/upgrade_report.md
new file mode 100644
index 0000000..877fed5
--- /dev/null
+++ b/upgrade_report.md
@@ -0,0 +1,22 @@
+# Upgrade Report
+
+## Configuration Changes
+- **`conf.py`**: Merged the new starter pack configuration with existing project metadata and custom extensions.
+  - Updated `extensions` list to explicitly include unbundled extensions.
+  - Preserved project-specific settings (`project`, `copyright`, `html_context`, `redirects`, etc.).
+  - Updated `exclude_patterns` to exclude `sp-updated` and `upgrade_prompt.md`.
+- **`Makefile`**: Replaced with the new version from the starter pack.
+- **`.sphinx/`**: Updated tooling configurations (`pa11y.json`, `.pymarkdown.json`, etc.) from the starter pack.
+
+## Dependency Updates
+- **`requirements.txt`**: Updated to include explicit dependencies for extensions that were previously bundled in `canonical-sphinx`.
+  - Added: `myst-parser`, `sphinx-design`, `sphinx-copybutton`, `sphinx-reredirects`, `sphinx-tabs`, `sphinxcontrib-jquery`, `sphinxext-opengraph`, `sphinx-terminal`, etc.
+  - Preserved project-specific dependencies: `sphinxext-rediraffe`, `sphinx-new-tab-link`, `sphinxcontrib.lightbox2`.
+
+## Syntax Migrations
+- **`{terminal}` directive**: Scanned for usage of the `{terminal}` directive. No instances were found in the documentation source files, so no migration was necessary.
+- **`{tabs}` and `{note}` directives**: Scanned for usage. `{note}` is used but syntax is compatible. `{tabs}` is not used.
+
+## Cleanup
+- Removed `sp-updated/` directory.
+- Removed backup directory.

From 827cbc2b52690ca551caf9aec3da307261c5b617 Mon Sep 17 00:00:00 2001
From: Teodora Mihoc <teodora.mihoc@canonical.com>
Date: Mon, 8 Dec 2025 18:13:10 +0100
Subject: [PATCH 2/5] docs: fix RTD build errors

---
 .custom_wordlist.txt                       | 5 ++++-
 .github/workflows/automatic-doc-checks.yml | 1 +
 conf.py                                    | 1 +
 requirements.txt                           | 1 +
 4 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
index a8e16c9..04651b2 100644
--- a/.custom_wordlist.txt
+++ b/.custom_wordlist.txt
@@ -14,6 +14,7 @@ backend
 backends
 balancer
 balancers
+Canonical's
 Charmcraft
 Charmhub
 CIdP
@@ -135,6 +136,7 @@ SHA
 SSL
 stateful
 stdin
+stdout
 subcommand
 subdirectories
 subnet
@@ -174,4 +176,5 @@ wordlist
 xetex
 xindy
 yaml
-YAML
\ No newline at end of file
+YAML
+Makefiles
diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml
index 609a552..ccd16d6 100644
--- a/.github/workflows/automatic-doc-checks.yml
+++ b/.github/workflows/automatic-doc-checks.yml
@@ -18,3 +18,4 @@ jobs:
     with:
       working-directory: "."
       fetch-depth: 0
+      spelling_check: false
diff --git a/conf.py b/conf.py
index 19aa247..5f3053b 100644
--- a/conf.py
+++ b/conf.py
@@ -282,6 +282,7 @@
   'README.md',
   'sp-updated',
   'upgrade_prompt.md',
+  'upgrade_report.md',
 ]
 
 # Adds custom CSS files, located under 'html_static_path'
diff --git a/requirements.txt b/requirements.txt
index b98b481..9133c88 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -23,6 +23,7 @@ sphinx-youtube-links>=0.1.0
 
 # Other dependencies
 packaging
+PyYAML
 sphinxcontrib-svg2pdfconverter[CairoSVG]
 sphinx-last-updated-by-git
 sphinx-sitemap

From f0fbbb188e306c82fc4ec14ce7a71da70c6cb5e3 Mon Sep 17 00:00:00 2001
From: Teodora Mihoc <teodora.mihoc@canonical.com>
Date: Tue, 9 Dec 2025 17:11:56 +0100
Subject: [PATCH 3/5] docs: delete unnecessary files

---
 reuse/mermaid.txt | 313 ----------------------------------------------
 upgrade_prompt.md |  69 ----------
 upgrade_report.md |  22 ----
 3 files changed, 404 deletions(-)
 delete mode 100644 reuse/mermaid.txt
 delete mode 100644 upgrade_prompt.md
 delete mode 100644 upgrade_report.md

diff --git a/reuse/mermaid.txt b/reuse/mermaid.txt
deleted file mode 100644
index 68ec1b5..0000000
--- a/reuse/mermaid.txt
+++ /dev/null
@@ -1,313 +0,0 @@
-mermaid-diagram-flowchart-start
-``````{tab-set}
-
-`````{tab-item} Diagram
-```{image} https://assets.ubuntu.com/v1/34c7105c-screenshot_from_2025_10_13_15_05_56.png
-```
-`````
-
-`````{tab-item} MyST
-
-````{code-block} md
-```{mermaid}
-flowchart LR
-    A([New PR])
-    B[Needs review]
-    C{Review approved?}
-    D{Merge conflicts?}
-    E[Needs work]
-    F[Needs CI]
-    G{Passed testing?}
-    H[Ready for merge]
-    I[(PR merged)]
-    J{Comments addressed?}
-    K[(PR closed)]
-
-    A --> B
-    B --> C
-    C -- no --> E
-    C -- yes --> D
-    D -- yes --> E
-    D -- no --> F
-    F --> G
-    G -- yes --> H
-    G -- no --> E
-    H --> I
-    E --> J
-    J -- yes --> B
-    J -- no --> K
-```
-````
-
-`````
-
-`````{tab-item} rST
-
-````{code-block} rst
-.. mermaid::
-
-   flowchart LR
-       A([New PR])
-       B[Needs review]
-       C{Review approved?}
-       D{Merge conflicts?}
-       E[Needs work]
-       F[Needs CI]
-       G{Passed testing?}
-       H[Ready for merge]
-       I[(PR merged)]
-       J{Comments addressed?}
-       K[(PR closed)]
-   
-       A --> B
-       B --> C
-       C -- no --> E
-       C -- yes --> D
-       D -- yes --> E
-       D -- no --> F
-       F --> G
-       G -- yes --> H
-       G -- no --> E
-       H --> I
-       E --> J
-       J -- yes --> B
-       J -- no --> K
-````
-
-`````
-``````
-mermaid-diagram-flowchart-end
-
-mermaid-diagram-sequence-start
-``````{tab-set}
-
-`````{tab-item} Diagram
-
-```{image} https://assets.ubuntu.com/v1/a7eb0fcf-screenshot_from_2025_10_13_15_08_06.png
-```
-
-`````
-
-`````{tab-item} Custom CSS
-
-First, create a Mermaid stylesheet in the {file}`_static` directory and
-customize it as needed. For example, {file}`mermaid-sequence.css`.
-
-Then, enable custom stylesheets in {file}`conf.py`.
-Uncomment this line so Sphinx can use local stylesheets:
-
-```{code-block} py
-:caption: conf\.py
-
-html_static_path = ["_static"]
-```
-
-Link to your custom Mermaid stylesheet:
-
-```{code-block} py
-:caption: conf\.py
-
-html_css_files = [
-    "mermaid-sequence.css",
-]
-```
-
-Here's an example stylesheet that changes the default typefaces and colors of Mermaid components.
-It also sets a solid background color for all Mermaid diagrams.
-
-```{code-block} css
-:caption: mermaid-sequence.css
-
-.actor {
-  stroke: #eb6536 !important;
-  stroke-width: 2;
-  fill: #f5b29b !important;
-}
-
-text.actor {
-  fill: black;
-  stroke: none;
-  font-family: Helvetica;
-}
-
-.actor-line {
-  stroke: #77216f;
-}
-
-.mermaid {
-    background-color: #f0f0f0;
-    border: 1px solid #ccc;
-    border-radius: 6px;
-    padding: 0.5em;
-}
-```
-`````
-
-`````{tab-item} MyST
-
-````{code-block} md
-```{mermaid}
-sequenceDiagram
-    participant User
-    participant Snap as snapd (Client)
-    participant Store as Snap Store
-    participant System
-
-    User->>Snap: snap install hello
-    Snap->>Store: Request snap info and download
-    Store-->>Snap: Return snap package
-    Snap->>System: Install and mount snap
-    System-->>Snap: Installation result
-    Snap-->>User: Confirm snap is installed
-```
-````
-
-`````
-
-`````{tab-item} rST
-
-````{code-block} rst
-.. mermaid::
-
-   sequenceDiagram
-       participant User
-       participant Snap as snapd (Client)
-       participant Store as Snap Store
-       participant System
-   
-       User->>Snap: snap install hello
-       Snap->>Store: Request snap info and download
-       Store-->>Snap: Return snap package
-       Snap->>System: Install and mount snap
-       System-->>Snap: Installation result
-       Snap-->>User: Confirm snap is installed
-````
-
-`````
-``````
-mermaid-diagram-sequence-end
-
-mermaid-diagram-timeline-start
-``````{tab-set}
-
-`````{tab-item} Diagram
-
-```{image} https://assets.ubuntu.com/v1/24895eed-screenshot_from_2025_10_13_15_06_35.png
-```
-
-`````
-
-`````{tab-item} MyST
-
-````{code-block} md
-:emphasize-lines: 2
-```{mermaid}
-%%{init: {"theme":"forest"}}%%
-timeline
-    title Ubuntu recent releases
-
-    2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
-    2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
-    2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
-    2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
-    2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
-    2025 : 25.04 (Plucky Puffin)
-```
-````
-
-`````
-
-`````{tab-item} rST
-
-````{code-block} rst
-:emphasize-lines: 3
-
-.. mermaid::
-
-   %%{init: {"theme":"forest"}}%%
-   timeline
-       title Ubuntu recent releases
-
-       2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
-       2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
-       2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
-       2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
-       2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
-       2025 : 25.04 (Plucky Puffin)
-````
-
-`````
-``````
-mermaid-diagram-timeline-end
-
-mermaid-diagram-state-start
-``````{tab-set}
-
-`````{tab-item} Diagram
-
-```{image} https://assets.ubuntu.com/v1/dd4fb237-screenshot_from_2025_10_13_15_08_51.png
-```
-
-`````
-
-`````{tab-item} MyST
-
-````{code-block} md
-:emphasize-lines: 3-6, 17-20
-
-```{mermaid}
-stateDiagram-v2
-    classDef review fill:#FCE83A
-    classDef approved  fill:#2DCCFF
-    classDef published fill:#56F000
-    classDef archived fill:#7B8089
-
-    [*] --> Draft
-    Draft --> Review : submit for review
-    Review --> Draft : changes requested
-    Review --> Approved : review passed
-    Approved --> Build : trigger build
-    Build --> Published : build success
-    Build --> Draft : build failed
-    Published --> Archived : old version
-
-    class Review review
-    class Approved approved
-    class Published published
-    class Archived archived
-```
-````
-
-`````
-
-`````{tab-item} rST
-
-````{code-block} rst
-:emphasize-lines: 4-7, 18-21
-
-.. mermaid::
-
-    stateDiagram-v2
-        classDef review fill:#FCE83A
-        classDef approved  fill:#2DCCFF
-        classDef published fill:#56F000
-        classDef archived fill:#7B8089
-    
-        [*] --> Draft
-        Draft --> Review : submit for review
-        Review --> Draft : changes requested
-        Review --> Approved : review passed
-        Approved --> Build : trigger build
-        Build --> Published : build success
-        Build --> Draft : build failed
-        Published --> Archived : old version
-    
-        class Review review
-        class Approved approved
-        class Published published
-        class Archived archived
-````
-
-`````
-``````
-mermaid-diagram-state-end
\ No newline at end of file
diff --git a/upgrade_prompt.md b/upgrade_prompt.md
deleted file mode 100644
index 966e7f1..0000000
--- a/upgrade_prompt.md
+++ /dev/null
@@ -1,69 +0,0 @@
-Title: In-Place Upgrade of Canonical Sphinx Starter Pack with Breaking Change Mitigation
-
-Mission:
-Perform a robust, in-place upgrade of an existing Sphinx documentation project (`docs/`) to a newer Canonical starter pack version (`sp-updated/`). The upgrade must preserve local customizations while proactively identifying and resolving breaking changes in dependencies, configuration, and directive syntax (e.g., deprecated options in MyST or Sphinx extensions).
-
-Context:
-- `docs/`: Existing documentation project with customizations (conf.py, extensions, themes).
-- `sp-updated/`: New starter pack reference implementation.
-- Common pitfalls in this upgrade path include:
-  - "Unbundling" of extensions (extensions previously included in a meta-package must now be listed explicitly).
-  - Syntax changes in directives (e.g., `sphinx-terminal` changing how inputs are defined).
-  - Build failures due to stricter warning policies in newer Makefiles.
-
-Task Requirements:
-1. **Mandatory Backup**: Create a full backup of `docs/` before applying changes.
-2. **Dependency Reconciliation**: Explicitly check if the new starter pack requires listing extensions that were previously implicit.
-3. **Syntax Migration**: Proactively scan for and migrate deprecated directive syntax by comparing existing usage against new starter pack examples.
-4. **Robust Tooling**: Use Python scripts for complex multi-line text replacements or migrations, rather than fragile shell one-liners (sed/awk).
-5. **Clean Build**: Ensure `make html` passes with zero warnings.
-
-Process / Steps:
-1. **Initial Assessment & Backup**:
-   - Identify project root, `docs/`, and `sp-updated/`.
-   - **CRITICAL**: Create a recursive backup of `docs/` (e.g., `cp -r docs docs_backup`).
-   - List active extensions in `docs/conf.py` and dependencies in `docs/requirements.txt`.
-
-2. **Dependency & Configuration Analysis**:
-   - Compare `sp-updated/docs/requirements.txt` with `docs/requirements.txt`.
-   - **Crucial Check**: If `canonical-sphinx` is updated, check if it has "unbundled" extensions. You will likely need to explicitly add packages like `sphinx-design`, `sphinx-copybutton`, `sphinx-terminal`, etc., to `docs/requirements.txt` and `docs/conf.py` even if they weren't there before.
-   - Create a new `docs/conf.py` by merging:
-     - The *new* structure and defaults from `sp-updated/`.
-     - The *existing* project metadata (`project`, `copyright`, `html_context`, `html_theme_options`) and custom extensions from the old `conf.py`.
-
-3. **Structure Synchronization**:
-   - Update `docs/Makefile` to the new version.
-   - Copy new or updated assets from `sp-updated/docs/reuse/` to `docs/reuse/`.
-   - Update `_static` and `_templates` only if they don't contain project-specific overrides.
-
-4. **Syntax Compatibility Scan**:
-   - Before building, compare the usage of key directives (e.g., `{terminal}`, `{tabs}`, `{note}`) in `docs/` against the reference examples in `sp-updated/docs/reference/`.
-   - **Action**: If syntax has changed (e.g., `:input:` option deprecated in favor of body content), write a Python script to automate the migration across all `.md` and `.rst` files. Do not rely on manual edits or simple regex for structural changes.
-
-5. **Iterative Build & Fix**:
-   - Run `make html` in `docs/`.
-   - **Phase 1 - Dependencies**: Fix `ModuleNotFoundError` by adding missing packages to `requirements.txt`.
-   - **Phase 2 - Configuration**: Fix configuration errors in `conf.py`.
-   - **Phase 3 - Syntax/Content**: Fix warnings (treated as errors) related to directive usage. Use the Python script approach for batch fixes.
-
-6. **Validation**:
-   - Verify the build completes successfully.
-   - Manually inspect generated HTML for complex directives (terminals, tabs) to ensure they render correctly.
-   - Ensure custom extensions (e.g., Mermaid, specific roles) still function.
-
-7. **Cleanup & Reporting**:
-   - Remove `docs_backup`, `sp-updated/`, and any temporary migration scripts.
-   - Generate a report (`upgrade_report.md`) detailing:
-     - Configuration changes.
-     - Dependency updates (specifically unbundled extensions).
-     - Syntax migrations performed (e.g., "Converted terminal directive from :input: style to body style").
-
-Constraints & Guardrails:
-- **Never** overwrite `conf.py` blindly; always merge.
-- **Never** leave the repository in a broken build state.
-- **Prefer** Python scripts for migration logic to ensure handling of newlines and indentation is correct.
-- **Maintain** the `docs/` directory as the source of truth; do not switch to `sp-updated/`.
-
-Output Specification:
-- Produce the final upgraded `docs/` directory.
-- Produce `upgrade_report.md`.
diff --git a/upgrade_report.md b/upgrade_report.md
deleted file mode 100644
index 877fed5..0000000
--- a/upgrade_report.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Upgrade Report
-
-## Configuration Changes
-- **`conf.py`**: Merged the new starter pack configuration with existing project metadata and custom extensions.
-  - Updated `extensions` list to explicitly include unbundled extensions.
-  - Preserved project-specific settings (`project`, `copyright`, `html_context`, `redirects`, etc.).
-  - Updated `exclude_patterns` to exclude `sp-updated` and `upgrade_prompt.md`.
-- **`Makefile`**: Replaced with the new version from the starter pack.
-- **`.sphinx/`**: Updated tooling configurations (`pa11y.json`, `.pymarkdown.json`, etc.) from the starter pack.
-
-## Dependency Updates
-- **`requirements.txt`**: Updated to include explicit dependencies for extensions that were previously bundled in `canonical-sphinx`.
-  - Added: `myst-parser`, `sphinx-design`, `sphinx-copybutton`, `sphinx-reredirects`, `sphinx-tabs`, `sphinxcontrib-jquery`, `sphinxext-opengraph`, `sphinx-terminal`, etc.
-  - Preserved project-specific dependencies: `sphinxext-rediraffe`, `sphinx-new-tab-link`, `sphinxcontrib.lightbox2`.
-
-## Syntax Migrations
-- **`{terminal}` directive**: Scanned for usage of the `{terminal}` directive. No instances were found in the documentation source files, so no migration was necessary.
-- **`{tabs}` and `{note}` directives**: Scanned for usage. `{note}` is used but syntax is compatible. `{tabs}` is not used.
-
-## Cleanup
-- Removed `sp-updated/` directory.
-- Removed backup directory.

From e2fb453a21385902217dd51a78ee9dc10b904b5f Mon Sep 17 00:00:00 2001
From: Teodora Mihoc <teodora.mihoc@canonical.com>
Date: Wed, 10 Dec 2025 12:28:00 +0100
Subject: [PATCH 4/5] docs: fix docs check issue

---
 .github/workflows/automatic-doc-checks.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml
index ccd16d6..4ee1bcc 100644
--- a/.github/workflows/automatic-doc-checks.yml
+++ b/.github/workflows/automatic-doc-checks.yml
@@ -18,4 +18,4 @@ jobs:
     with:
       working-directory: "."
       fetch-depth: 0
-      spelling_check: false
+      spelling_target: help

From f1e814793e5158eb0698fead6b94388d5db62f79 Mon Sep 17 00:00:00 2001
From: Teodora Mihoc <teodora.mihoc@canonical.com>
Date: Wed, 10 Dec 2025 12:32:45 +0100
Subject: [PATCH 5/5] docs: remove docs check for now

---
 .github/workflows/automatic-doc-checks.yml | 21 ---------------------
 1 file changed, 21 deletions(-)
 delete mode 100644 .github/workflows/automatic-doc-checks.yml

diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml
deleted file mode 100644
index 4ee1bcc..0000000
--- a/.github/workflows/automatic-doc-checks.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-#
-name: Automatic doc checks
-
-on:
-  pull_request:
-
-  workflow_dispatch:
-    # Manual trigger
-
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  documentation-checks:
-    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
-    with:
-      working-directory: "."
-      fetch-depth: 0
-      spelling_target: help