docs: add docs for RTD

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

@@ -0,0 +1,18 @@
+name: Main Documentation Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Manual trigger
+  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: "."

.github/workflows/markdown-style-checks.yml

@@ -0,0 +1,21 @@
+name: "Linter for Markdown"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     
+      - uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          config: "docs-rtd/.sphinx/.markdownlint.json"
+

.github/workflows/periodic-style-checks.yml

@@ -0,0 +1,19 @@
+name: Periodic Style Checks
+
+on:
+  schedule:
+    - cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday
+
+jobs:
+  vale:
+    name: Style checker
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: "sp-docs"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run vale
+        run: |
+          make vale

.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -0,0 +1,48 @@
+# The purpose of this workflow file is to confirm that the Sphinx
+# virtual environment can be built from source, consequently documenting
+# the packages required in the build environment to do that.
+#
+# This is needed because some projects embeds the documentation into built
+# artifacts which involves rendering the documentation on the target
+# architecture.
+#
+# Depending on the architecture, pip may or may not have already built wheels
+# available, and as such we need to make sure building wheels from source can
+# succeed.
+name: Check and document build requirements for Sphinx venv
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          set -ex
+          sudo apt -y install \
+            cargo \
+            libpython3-dev \
+            libxml2-dev \
+            libxslt1-dev \
+            make \
+            python3-venv \
+            rustc
+      - name: Build Sphinx venv
+        working-directory: "docs"
+        run: |
+          set -ex
+          make -f docs-rtd/Makefile.sp \
+            sp-install \
+            PIPOPTS="--no-binary :all:" \
+            || ( cat .sphinx/venv/pip_install.log && exit 1 )

.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: docs-rtd/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: docs-rtd/.sphinx/requirements.txt

.wokeignore

@@ -0,0 +1 @@
+docs-rtd/.wokeignore

docs-rtd/.gitignore

@@ -0,0 +1,17 @@
+
+# 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
+sp-docs/_build

docs-rtd/.sphinx/.markdownlint.json

@@ -0,0 +1,16 @@
+{
+    "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
+}

docs-rtd/.sphinx/.wordlist.txt

@@ -0,0 +1,64 @@
+ACME
+ACME's
+addons
+AGPLv
+API
+APIs
+balancer
+Charmhub
+CLI
+DCO
+Diátaxis
+Dqlite
+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
+TODO
+Ubuntu
+UI
+UUID
+VM
+webhook
+YAML

docs-rtd/.sphinx/_static/css/pdf.css

@@ -0,0 +1,15 @@
+/* Only relevant for specific PDF generation issues */
+
+.rubric>.hclass2 {
+    display: block;
+    font-size: 2em;
+    border-radius: .5rem;
+    font-weight: 300;
+    line-height: 1.25;
+    margin-top: 1.75rem;
+    margin-right: -0.5rem;
+    margin-bottom: 0.5rem;
+    margin-left: -0.5rem;
+    padding-left: .5rem;
+    padding-right: .5rem;
+}

docs-rtd/.sphinx/_templates/header.html

@@ -0,0 +1,52 @@
+<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">
+
+          {% if discourse %}
+          <li>
+            <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Discourse</a>
+          </li>
+          {% endif %}
+
+          {% if mattermost %}
+          <li>
+            <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+          </li>
+          {% endif %}
+
+          {% if matrix %}
+          <li>
+            <a href="{{ matrix }}" class="p-navigation__sub-link p-dropdown__link">Matrix</a>
+          </li>
+          {% endif %}
+
+          {% if github_url %}
+          <li>
+            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+          {% endif %}
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>