docs: Set up RTD documentation project

[erinecon]

Overview

This PR sets up a Read the Docs (RTD) documentation project for the Discourse charm, migrating from Charmhub-hosted documentation to a Sphinx/RTD-based setup using the Canonical starter pack.

Changes

Phase 1: Project setup

• Copy Sphinx starter pack files (.readthedocs.yaml, conf.py, Makefile, etc.)
• Create docs_rtd.yaml workflow for RTD CI checks
• Add CLA check workflow
• Configure conf.py with project-specific settings
• Add Mermaid extension and fix diagram fences
• Pin all dependencies in requirements.txt

Phase 2: Content structure

• Add SEO metadata and toctrees to index files
• Create explanation/index.md landing page
• Add reference targets to all documentation files
• Set up cookie banner and URL-rewrite script
• Convert blockquote admonitions to MyST syntax

Phase 3: Finalization

• Create contribute.rst page from template
• Update Juju links to use intersphinx refs where possible
• Add Documentation section to README.md
• Update repository files for RTD compatibility
• Fix heading levels and markdown formatting

---

For reviewers

High priority — verify correctness

File	What to verify
docs/conf.py	Project name ("Discourse charm"), product_page, github_url, intersphinx mappings
docs/_static/js/overwrite_links.js	newDomain is set to canonical.com/juju/docs/discourse-k8s-charm; oldDomain is <<RtDURL>> placeholder
docs/index.md	Home page structure, toctree entries, metadata
docs/how-to/contribute.rst	Template with TODO comments
docs/explanation/index.md	New file — review all content
docs/how-to/index.md, docs/reference/index.md	Existing files — toctree/anchor additions
README.md	New Documentation section

Medium priority — structural and CI changes

File	What to verify
.github/workflows/docs_rtd.yaml	New workflow calling operator-workflows
.github/workflows/docs.yaml	vale-files scoping added
docs/requirements.txt	Version pins
.licenserc.yaml	paths-ignore for docs
pyproject.toml	Codespell skip patterns
.github/pull_request_template.md	Charmhub reference removed

Low priority — copied verbatim from the starter pack (click to expand)

• .readthedocs.yaml
• docs/.gitignore
• docs/Makefile
• docs/_templates/*
• .github/workflows/cla-check.yml
• docs/redirects.txt
• docs/.custom_wordlist.txt
• docs/_dev/.pymarkdown.json

---

Items requiring human action

1. Set up the RTD project in Read the Docs

   • Organization: Canonical / Platform Engineering
   • Project name: "Discourse K8s charm"
   • URL versioning: Single version without translations
   • Set default branch to docs/rtd-setup initially, switch to main after merge

2. Update oldDomain in docs/_static/js/overwrite_links.js once the RTD URL is known

3. Update docs/how-to/contribute.rst — review TODO comments

4. Update charmcraft.yaml or metadata.yaml — update documentation key once the RTD URL is known

5. Run quality checks before merge:

   cd docs
   make run        # Check rendering
   make spelling   # Fix spelling errors
   make linkcheck  # Fix broken links
   make vale       # Fix style errors

6. Post-merge: Update RTD backend to use main as default branch; set version to Public

---

Pre-existing issues

Some markdown lint errors remain from the source documentation (blank lines around code fences, etc.). These are pre-existing and should be addressed in a follow-up PR if needed.

[erinecon]

Moving to a draft so I can inspect the output and iterate on the skill that put this PR together.