feat(docs): use canonical starter pack

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

@@ -0,0 +1,49 @@
+name: Main Documentation Checks
+
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docchecks:
+    name: Run documentation checks
+    runs-on: ubuntu-latest
+    outputs:
+      result_spelling: ${{ steps.spellcheck-step.outcome }}
+      result_woke: ${{ steps.woke-step.outcome }}
+      result_links: ${{ steps.linkcheck-step.outcome }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Remove upstream unused files
+        run: |
+          rm -f docs/sphinx-docs-starter-pack/doc-cheat-sheet*
+
+      - name: Spell Check
+        id: spellcheck-step
+        if: success() || failure()
+        uses: canonical/documentation-workflows/spellcheck@main
+        with:
+          working-directory: "docs"
+
+      - name: Inclusive Language Check
+        id: woke-step
+        if: success() || failure()
+        uses: canonical/documentation-workflows/inclusive-language@main
+        with:
+          working-directory: "docs"
+
+      - name: Link Check
+        id: linkcheck-step
+        if: success() || failure()
+        uses: canonical/documentation-workflows/linkcheck@main
+        with:
+          working-directory: "docs"

.github/workflows/docs.yaml

@@ -20,6 +20,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          submodules: recursive
       - name: Setup Python
         uses: actions/setup-python@v4
         with:

.gitignore

@@ -70,6 +70,11 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/.sphinx/venv/
+docs/.sphinx/warnings.txt
+docs/.sphinx/.wordlist.dic
+docs/.sphinx/.doctrees/
+docs/sphinx-docs-starter-pack/*
 
 # PyBuilder
 target/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/sphinx-docs-starter-pack"]
+	path = docs/sphinx-docs-starter-pack
+	url = https://github.com/canonical/sphinx-docs-starter-pack.git

.readthedocs.yml

@@ -5,23 +5,29 @@
 # Required
 version: 2
 
+submodules:
+  include:
+    - docs/sphinx-docs-starter-pack
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
+  builder: dirhtml
   configuration: docs/conf.py
+  fail_on_warning: true
 
-# Optionally build your docs in additional formats such as PDF
+# If using Sphinx, optionally build your docs in additional formats such as PDF
 formats:
   - pdf
-  - epub
-
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3"
 
+# Optionally declare the Python requirements required to build your docs
 python:
   install:
+    - requirements: docs/.sphinx/requirements.txt
     - method: pip
       path: .
-      extra_requirements:
-        - docs

docs/.custom_wordlist.txt

@@ -0,0 +1,17 @@
+Changelog
+cli
+datetime
+http
+https
+io
+initialization
+initialized
+NotLoggedIn
+keyring
+StoreClient
+snapcraft
+SSO
+ubuntu
+unregistering
+url
+whoami

docs/.sphinx/requirements.txt

@@ -0,0 +1,14 @@
+furo==2023.9.10
+lxd-sphinx-extensions==0.0.14
+myst-parser==2.0.0
+pyspelling==2.9
+sphinx==7.2.6
+sphinx-autobuild==2021.3.14
+sphinxcontrib-jquery==4.1
+sphinx-copybutton==0.5.2
+sphinx-design==0.5.0
+sphinxext-opengraph==0.8.2
+sphinx-lint==0.6.8
+sphinx-notfound-page==1.0.0
+sphinx-reredirects==0.1.2
+sphinx-tabs==3.4.1

docs/.wordlist.txt

@@ -0,0 +1 @@
+sphinx-docs-starter-pack/.wordlist.txt

docs/Makefile

@@ -0,0 +1,130 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -c . -d .sphinx/.doctrees
+SPHINXBUILD   ?= sphinx-build
+SPHINXDIR     = .sphinx
+SOURCEDIR     = .
+BUILDDIR      = _build
+VENVDIR       = $(SPHINXDIR)/venv
+VENV          = $(VENVDIR)/bin/activate
+
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help
+
+# Explicit target avoids fall-through to the "Makefile" target.
+$(SPHINXDIR)/requirements.txt:
+	test -f $(SPHINXDIR)/requirements.txt
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR): $(SPHINXDIR)/requirements.txt
+	@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
+	@echo "\n" \
+        "--------------------------------------------------------------- \n" \
+        "* watch, build and serve the documentation: make run \n" \
+        "* only build: make html \n" \
+        "* only serve: make serve \n" \
+        "* clean built doc files: make clean-doc \n" \
+        "* clean full environment: make clean \n" \
+        "* check spelling: make spelling \n" \
+        "* check inclusive language: make woke \n" \
+        "* other possible targets: make <press TAB twice> \n" \
+        "--------------------------------------------------------------- \n"
+	@touch $(VENVDIR)
+
+
+woke-install:
+	@type woke >/dev/null 2>&1 || \
+        { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
+
+.PHONY:  woke-install
+
+
+install: $(VENVDIR) woke-install
+
+.PHONY:  install
+
+
+run: install
+	. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \
+	$(SPHINXOPTS)
+
+.PHONY: run
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \
+        -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+.PHONY: html
+
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" \
+        -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+.PHONY: epub
+
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server 8000
+
+.PHONY: serve
+
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o \
+        -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf .sphinx/.doctrees
+
+.PHONY: clean
+
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+
+.PHONY: clean-doc
+
+
+spelling: html
+	. $(VENV) ; python3 -m pyspelling -c sphinx-docs-starter-pack/.sphinx/spellingcheck.yaml
+
+.PHONY: spelling
+
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" \
+	$(SPHINXOPTS)
+
+.PHONY: linkcheck
+
+
+woke: woke-install
+	woke *.rst **/*.rst \
+		--exit-1-on-failure \
+        -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
+
+.PHONY: woke
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	. $(VENV); \
+        $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: Makefile