Integrate documentation starter pack into repository (#662)

* add starter pack and raw markdown docs

* add CI doc checks

* clean up rogue files and add closing toctree backticks

* fix H1 headings, end delimiters, and how-to/ references

* fix sphinx build errors

* update essential conf.py parameters

* remove ci checks to avoid unnecessary runner use

* fix typo

* change main branch for rtd builds

* remove sync_docs workflow and ignore docs folder in CI checks

Author: a-velasco

.github/workflows/check_libs.yaml

@@ -14,6 +14,7 @@ on:
       - 'LICENSE'
       - '**.md'
       - 'renovate.json'
+      - 'docs/**'
 
 jobs:
   lib-check:

.github/workflows/ci.yaml

@@ -11,7 +11,7 @@ on:
     paths-ignore:
       - '**.md'
       - '.github/renovate.json5'
-      - '.github/workflows/sync_docs.yaml'
+      - 'docs/**'
   schedule:
     - cron: '53 0 * * *'  # Daily at 00:53 UTC
   # Triggered on push to branch "main" by .github/workflows/release.yaml

.github/workflows/release.yaml

@@ -10,7 +10,6 @@ on:
       - 'docs/**'
       - '.github/renovate.json5'
       - '.github/workflows/check_libs.yaml'
-      - '.github/workflows/sync_docs.yaml'
 
 jobs:
   ci-tests:

.github/workflows/sync_docs.yaml

@@ -0,0 +1,39 @@
+# .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:
+    post_checkout:
+    - git fetch --unshallow || true
+    # Cancel building pull requests when there aren't changed in the docs directory.
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/docs-dev -- 'docs/' '.readthedocs.yaml';
+      then
+        exit 183;
+      fi
+
+# 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/requirements.txt

.readthedocs.yaml

@@ -2,7 +2,6 @@
 [![CharmHub Badge](https://charmhub.io/mysql/badge.svg)](https://charmhub.io/mysql)
 [![Release](https://github.com/canonical/mysql-operator/actions/workflows/release.yaml/badge.svg)](https://github.com/canonical/mysql-operator/actions/workflows/release.yaml)
 [![Tests](https://github.com/canonical/mysql-operator/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/canonical/mysql-operator/actions/workflows/ci.yaml?query=branch%3Amain)
-[![Docs](https://github.com/canonical/mysql-operator/actions/workflows/sync_docs.yaml/badge.svg)](https://github.com/canonical/mysql-operator/actions/workflows/sync_docs.yaml)
 
 ## Description
 

README.md

@@ -0,0 +1,65 @@
+# Leave a blank line at the end of this file to support concatenation
+backend
+backends
+Charmcraft
+cjk
+cryptographically
+dvipng
+fonts
+freefont
+github
+GPG
+gyre
+https
+html
+io
+Intersphinx
+lang
+LaTeX
+latexmk
+Multipass
+otf
+plantuml
+PNG
+Pygments
+pymarkdown
+QEMU
+Rockcraft
+readthedocs
+rst
+sitemapindex
+subproject
+subprojects
+SVG
+tex
+texlive
+TOC
+toctree
+txt
+uncommenting
+utils
+VMs
+WCAG
+whitespace
+whitespaces
+wordlist
+xetex
+xindy
+xml
+ip
+spread_test_example
+Furo
+PDF
+Open Graph
+MyST
+YouTube
+reStructuredText
+GitHub
+Sphinx
+URL
+PR
+Read the Docs
+Spread
+landscape
+lastmod
+yaml

docs/.custom_wordlist.txt

@@ -0,0 +1,26 @@
+# Environment
+*env*/
+.sphinx/venv/
+
+# Sphinx
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/update/
+.sphinx/node_modules/
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
+_build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
+.DS_Store
+__pycache__
+.idea/
+.vscode/

docs/.gitignore

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: make-spelling
+        name: Run make spelling
+        entry: make -C docs spelling
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-linkcheck
+        name: Run make linkcheck
+        entry: make -C docs linkcheck
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-woke
+        name: Run make woke
+        entry: make -C docs woke
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$

docs/.sphinx/.pre-commit-config.yaml

@@ -0,0 +1,46 @@
+{
+    "plugins": {
+        "selectively_enable_rules": true,
+        "heading-style": {
+            "enabled": true,
+            "style": "atx"
+        },
+        "commands-show-output": {
+            "enabled": true
+        },
+        "no-missing-space-atx": {
+            "enabled": true
+        },
+        "blanks-around-headings": {
+            "enabled": true
+        },
+        "heading-start-left": {
+            "enabled": true
+        },
+        "no-trailing-punctuation": {
+            "enabled": true,
+            "punctuation": ".,;。，；"
+        },
+        "blanks-around-fences": {
+            "enabled": true,
+            "list_items": false
+        },
+        "blanks-around-lists": {
+            "enabled": true
+        },
+        "hr-style": {
+            "enabled": true
+        },
+        "no-empty-links": {
+            "enabled": true
+        },
+        "no-alt-text": {
+            "enabled": true
+        }
+    },
+    "extensions": {
+        "front-matter" : {
+            "enabled" : true
+        }
+    }
+}