Add all files

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

@@ -0,0 +1,16 @@
+name: Main Documentation Checks
+
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+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: '.'

.gitignore

@@ -0,0 +1,16 @@
+
+# Starter pack rules start here
+/*env*/
+.sphinx/venv/
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/node_modules/
+package*.json
+_build
+.DS_Store
+__pycache__
+.idea/
+.vscode/
+.sphinx/styles/*
+.sphinx/vale.ini

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    pre_install:
+      - git fetch --unshallow || true
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: ./conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: ./.sphinx/requirements.txt

.sphinx/.wordlist.txt

@@ -0,0 +1,61 @@
+# This wordlist is from the Sphinx starter pack and should not be
+# modified. Add any custom terms to .custom_wordlist.txt instead.
+
+addons
+API
+APIs
+balancer
+Charmhub
+CLI
+Diátaxis
+dropdown
+EBS
+EKS
+enablement
+favicon
+Furo
+Git
+GitHub
+Grafana
+IAM
+installable
+JSON
+Juju
+Kubeflow
+Kubernetes
+Launchpad
+linter
+LTS
+LXD
+Makefile
+Makefiles
+Matrix
+Mattermost
+MicroCeph
+MicroCloud
+MicroOVN
+MyST
+namespace
+namespaces
+NodePort
+Numbat
+observability
+OEM
+OLM
+Permalink
+pre
+Quickstart
+ReadMe
+reST
+reStructuredText
+roadmap
+RTD
+subdirectories
+subfolders
+subtree
+Ubuntu
+UI
+UUID
+VM
+webhook
+YAML

.sphinx/_templates/header.html

@@ -0,0 +1,36 @@
+<header id="header" class="p-navigation">
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <a class="p-logo" href="https://{{ product_page }}" aria-current="page">
+          <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
+          <div class="p-logo-text p-heading--4">{{ project }}
+          </div>
+        </a>
+      </li>
+
+      <li class="nav-ubuntu-com">
+        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
+      </li>
+
+      <li>
+        <a href="#" class="p-navigation__link nav-more-links">More resources</a>
+        <ul class="more-links-dropdown">
+
+          <li>
+            <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Forum</a>
+          </li>
+
+          <li>
+            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>

.sphinx/get_vale_conf.py

@@ -0,0 +1,29 @@
+#! /usr/bin/env python
+
+import requests
+import os
+
+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"
+    r = requests.get(url)
+    for item in r.json():
+        download = requests.get(item["download_url"])
+        file = open(".sphinx/styles/Canonical/" + item["name"], "w")
+        file.write(download.text)
+        file.close()
+
+    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()

.sphinx/pa11y.json

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

.sphinx/requirements.txt

@@ -0,0 +1,2 @@
+git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx
+sphinx-autobuild

.sphinx/spellingcheck.yaml

@@ -0,0 +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

.wokeignore

@@ -0,0 +1,4 @@
+# the cheat sheets contain a link to a repository with a block word which we
+# cannot avoid for now, ie
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+doc-cheat-sheet*

Makefile

@@ -0,0 +1,30 @@
+# 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.
+#
+# 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.
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@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 links:                               make linkcheck \n" \
+        "* check spelling:                            make spelling \n" \
+        "* check spelling (without building again):   make spellcheck \n" \
+        "* check inclusive language:                  make woke \n" \
+        "* check accessibility:                       make pa11y \n" \
+        "* check style guide compliance:              make vale \n" \
+        "* check style guide compliance on target:    make vale TARGET=* \n" \
+        "* other possible targets:                    make <TAB twice> \n" \
+        "------------------------------------------------------------- \n"
+
+%:
+	$(MAKE) -f Makefile.sp sp-$@

Makefile.sp

@@ -0,0 +1,110 @@
+# 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
+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-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-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:
+	. $(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)