chore(docs): set up RTD documentation project (charmkeeper)

[erinecon]

Summary

This PR sets up a Read the Docs (RTD) documentation project for the Content Cache Operators repository, based on the Canonical sphinx-docs-starter-pack.

Note: This PR was prepared automatically with the help of charmkeeper.

Prep work: consolidate docs

The repository previously had documentation split across two directories:

• content-cache/docs/ — main charm docs (tutorial, 4 how-to guides)
• content-cache-backends-config/docs/ — subordinate charm docs (index + contribute)

These have been consolidated into a single top-level docs/ directory covering both charms:

• docs/index.md — unified home page (Content Cache + Backends Config overview, WIP note preserved)
• docs/how-to/ — all how-to guides (contribute, enable-cos, enable-https, upgrade)
• docs/tutorial/ — getting started tutorial
• Stale references in README.md and CONTRIBUTING.md files updated

RTD infrastructure

• .readthedocs.yaml added
• .github/workflows/docs_rtd.yaml added (calls canonical/operator-workflows RTD workflow)
• docs/conf.py configured: project name, discourse/matrix links, github_url, product_page, juju + starter-pack intersphinx mappings, cookie banner, Mermaid extension
• All dependencies pinned (myst-parser==4.0.1 as required)
• Vale wordlist (docs/.custom_wordlist.txt) and mermaid exclusion in .sphinx/vale.ini
• Subdirectory index pages and MyST anchor targets added
• docs/how-to/contribute.rst created (replaces contribute.md) with AI usage policy
• docs/redirects.txt added (empty, satisfies sphinx-rerediraffe)
• .licenserc.yaml updated to exclude docs/**, .readthedocs.yaml, *.rst
• Root README.md updated with ## Documentation section

Build verification

All local checks pass on this branch:

• make html → build succeeded ✅
• make lint-md → 0 errors ✅
• make vale → 0 errors, 0 warnings ✅

Note: The "check URLs" workflow is expected to fail as there is no RTD project in the main branch.

Action items for humans

The following require human action outside this repository:

1. Set up the RTD project at app.readthedocs.com:

   • Organization and team: "Canonical / Platform Engineering"
   • Project name: "Content Cache Operators charm"
   • URL versioning: Single version without translations
   • Set default branch to charmkeeper/rtd-docs-setup initially; switch to main after merge
   • Privacy level: Private during setup, Public when ready
   • Enable "Build pull requests for this project"
   • Add as subproject of "Ubuntu documentation library" (may require a Technical Author)

2. Update conf.py once the RTD URL is known:

   • Uncomment and set ogp_site_url to the RTD project URL
   • Uncomment and set slug to the RTD project slug

3. Update metadata.yaml in both charm directories: replace the docs: key with the new RTD URL (once known).

4. Review TODOs in docs/how-to/contribute.rst (links to CONTRIBUTING.md, RTD URL).

5. Verify the cookie banner in a browser:

   cd docs && make clean && make install && make run

   Open in an incognito window and confirm the consent banner works.

6. Run remaining quality checks before merging:

   make spelling   # Fix spelling errors
   make linkcheck  # Fix broken links

   Note: The tutorial contains a link to juju.is/docs/juju/set-up--tear-down-your-test-environment (old URL) marked with a TODO comment — a human should verify the correct intersphinx target.

7. Post-merge:

   • Switch RTD default branch to main
   • Set Default version to Public
   • Archive and lock old Discourse pages once RTD migration is verified
   • Add to canonical-repo-automation if applicable

[github-actions]

Test results for commit 2df0b8d

Test coverage for 2df0b8d

Name            Stmts   Miss Branch BrPart  Cover   Missing
-----------------------------------------------------------
src/charm.py       47      0      6      0   100%
src/errors.py       1      0      0      0   100%
src/state.py      139      0     32      0   100%
-----------------------------------------------------------
TOTAL             187      0     38      0   100%

Static code analysis report

Run started:2026-04-16 16:46:59.807894+00:00

Test results:
  No issues identified.

Code scanned:
  Total lines of code: 986
  Total lines skipped (#nosec): 0
  Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 0

Run metrics:
  Total issues (by severity):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
  Total issues (by confidence):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
Files skipped (0):

[github-actions]

Test results for commit 2df0b8d

Test coverage for 2df0b8d

Name                   Stmts   Miss Branch BrPart  Cover   Missing
------------------------------------------------------------------
src/certificates.py       21      2      6      2    85%   65-68
src/charm.py             106     12      8      0    89%   64-65, 120, 149, 153-156, 211-213, 223-225
src/errors.py             16      0      0      0   100%
src/nginx_manager.py     199     36     16      4    81%   207, 213-219, 224-226, 229, 277-279, 295-297, 337-342, 417-419, 438-442, 461->463, 543-548
src/state.py             163     13     34      1    92%   154-159, 429-439
src/utilities.py          13      0      0      0   100%
------------------------------------------------------------------
TOTAL                    518     63     64      7    88%

Static code analysis report

Run started:2026-04-16 16:01:23.645477+00:00

Test results:
  No issues identified.

Code scanned:
  Total lines of code: 1208
  Total lines skipped (#nosec): 0
  Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 2

Run metrics:
  Total issues (by severity):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
  Total issues (by confidence):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
Files skipped (0):