Add the Spinx starter pack for RTD site (ISD-2738) (#16)

* enable starter pack

* customize the setup

* update home page

* update working directory in CI workflows

* update hardcoded sphinx venv dir

* update environment variables in Makefile

* update environment variables

* un-hardcode directory

* un-hardcode another directory

* revert env var changes

* add navigational structure for tutorials, how-to's, explanations

* update how to contribute page

* navigation changes

* update contributing guide

* update linkcheck ignore list

* update custom spelling list

* update changelog

* update README for markdown-lint

* make woke happy

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* move license info in .sh riles

* update license yaml

* remove license info from metrics sh

* update license ignore yaml

* move changelog entry under unreleased

* update ubuntu os version for RTD

* update python version for RTD

* update line_length

* add markdown cheat sheet

* make lint test happy

* fix unit test

* update unit test installation script

* revert changes for unit test

* trigger CI

* update .wokeignore file path

* update .woke.yaml ignore_files

* revert changes in .wokeignore

* revert .woke.yaml changes, add files to .gitignore

* add docs files to root .gitignore

* try to make vale happy

* update spellcheck to US English, update docs

* revert changes to .gitignore

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

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

@@ -0,0 +1,19 @@
+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: "docs"
+      fetch-depth: 0

.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/.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 Makefile.sp \
+            sp-install \
+            PIPOPTS="--no-binary :all:" \
+            || ( cat .sphinx/venv/pip_install.log && exit 1 )

.gitignore

@@ -162,3 +162,4 @@ cython_debug/
 *.charm
 *.rock
 !examples/**/lib
+

.licenserc.yaml

@@ -10,6 +10,7 @@ header:
   paths-ignore:
     - '.github/**'
     - '.woke.yaml'
+    - '.wokeignore'
     - '**/*.sum'
     - '**/*.json'
     - '**/*.j2'
@@ -33,4 +34,5 @@ header:
     - 'examples/django/charm/lib/charms/redis_k8s/v0/redis.py'
     - 'examples/flask/lib/charms/redis_k8s/v0/redis.py'
     - 'examples/go/charm/lib/charms/redis_k8s/v0/redis.py'
+    - 'docs/**'
   comment: on-failure

.wokeignore

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

CHANGELOG.md

@@ -6,3 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## 2024-11-29
+
+### Changes
+
+Added a `docs` folder to hold the
+[Canonical Sphinx starter pack](https://github.com/canonical/sphinx-docs-starter-pack)
+and to eventually publish the docs on Read the Docs.

README.md

@@ -57,10 +57,12 @@ Read the
 for more!
 
 Additional resources:
+
 * [Tutorial to build a rock for a Flask application](https://documentation.ubuntu.com/rockcraft/en/latest/tutorial/flask/)
 * [Charmcraft `flask-framework` reference](https://juju.is/docs/sdk/charmcraft-extension-flask-framework)
 * [Charmcraft `flask-framework` how to guides](https://juju.is/docs/sdk/build-a-paas-charm)
-* [Rockcraft `flask-framework` reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/)
+* [Rockcraft`flask-framework`
+   reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/)
 
 ## Contributing
 
@@ -76,15 +78,19 @@ through below.
 1. Please write a proposal on the
   [charm topic on discourse](https://discourse.charmhub.io/c/charm/41). This
   should cover things like:
+
   * The integration you intend add
   * For each of the frameworks that PaaS Charm supports:
+
     - The commonly used package(s) to make use of the integration
     - The environment variables, configuration etc. that would be made available
       to the app
     - An example for how to use the integration within an app
+
   * The proposed implementation in `paas-app`. Take a look at
     [`charm.py`](paas_charm/_gunicorn/charm.py) for `gunicorn` based
     frameworks for integration examples.
+
 1. Update the
   [reference](https://juju.is/docs/sdk/charmcraft-extension-flask-framework)
   with the new integration
@@ -101,6 +107,7 @@ below.
 1. Please write a proposal on the
   [charm topic on discourse](https://discourse.charmhub.io/c/charm/41). This
   should cover things like:
+
   * The programming language and framework you are thinking of
   * Create an example `rockcraft.yaml` file and build a working OCI image. To
     see an example for `flask`, install Rockcraft and run
@@ -115,6 +122,7 @@ below.
   * The requirements and conventions for how users need to configure their app
     to work with PaaS Charm
   * Which web server to use
+
 1. Raise a pull request to [rockcraft](https://github.com/canonical/rockcraft)
   adding a new extension and profile for the framework. This is the flask
   [profile](https://github.com/canonical/rockcraft/blob/fdd2dee18c81b12f25e6624a5a48f9f1ac9fdb90/rockcraft/commands/init.py#L79)

docs/.custom_wordlist.txt

@@ -0,0 +1,2 @@
+Charmcraft
+Rockcraft

docs/.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/.readthedocs.yaml

@@ -0,0 +1,33 @@
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+# .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-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    pre_install:
+      - git fetch --unshallow || true
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/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/.sphinx/requirements.txt

docs/.sphinx/.markdownlint.json

@@ -0,0 +1,16 @@
+{
+    "default": false,
+    "MD003": { "style": "atx" },
+    "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 120},
+    "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/.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/.sphinx/_static/css/pdf.css

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2024 Canonical Ltd.
+ * See LICENSE file for licensing details.
+ */
+
+/* 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;
+}