doc: docs tooling and configuration updates

[minaelee]

Updates to MicroCloud docs tooling and configuration for improvements as well as to align with standard Canonical docs tooling (Sphinx Stack 1.6, formerly known as Sphinx Starter Pack), including:

• Remove build_requirements.py and related code to dynamically build requirements.txt. Static file provided instead.
• Merge conf_py & custom_conf.py, and Makefile & Makefile.sp, and bring merged versions into alignment with Sphinx Stack. Includes using doc/.venv now instead of doc/.sphinx/venv for virtual environment directory at build time.
• Use Vale for spelling and woke checks; fix newly flagged issues by Vale.
• Use the canonical-sphinx extension while preserving MicroCloud customizations; remove use of canonical-sphinx-extensions.
• Removing canonical-sphinx-extensions required adding back in some extensions previously bundled with it, including sphinx-terminal, which in its un-bundled form has a difference in usage (the :input: option is now handled differently). Update usage of {terminal} directive.
• To align with Sphinx Stack directory structure, move _templates and _static directories out from doc/.sphinx/ to doc/, and substitutions.yaml from doc/ to doc/reuse.
• Add SINGLE_BUILD=True to linkcheck make target to prevent GH CI from warning and exiting linkcheck when it tries and fails to find the integration files.
• Replace sphinx-reredirects extension with sphinx-rerediraffe, the new default URL redirecter.
• Update configuration paths for MicroCeph.
• Remove RTD search support (RTD search is already disabled in MicroCloud docs due to inconsistent behavior).
• Add ubuntu.com to the linkcheck ignore list (despite being up, the site has been failing every linkcheck recently and I suspect this is due to increased protection measures).
• Add .sphinx/version file to record last version of sphinx-stack this docs set was updated against.

[minaelee]

Note: RTD build has been failing for the past hour. I tried to debug it but nothing helped, and then I thought to check other projects with recent RTD builds, and it looks like every build within the past hour on RTD has failed. Could be a GitHub issue or RTD issue. Either way, I'll wait to see if it is resolved in the morning.

[roosterfish]

Note: RTD build has been failing for the past hour. I tried to debug it but nothing helped, and then I thought to check other projects with recent RTD builds, and it looks like every build within the past hour on RTD has failed. Could be a GitHub issue or RTD issue. Either way, I'll wait to see if it is resolved in the morning.

Also the link checks are quite unstable over the last days, lots of timeouts. Likely related to the recent issues?

[Copilot]

Pull request overview

This PR updates MicroCloud’s documentation toolchain and Sphinx configuration to align with Canonical’s Sphinx Stack (1.6) and associated conventions, including changes to redirects, linting (Vale/woke), requirements management, and template/static layout.

Changes:

• Replace dynamic/docs-starter-pack requirements generation with a static doc/requirements.txt, and migrate config into a single doc/conf.py.
• Adopt Vale-based style/spelling checks and update doc examples to match sphinx-terminal directive behavior changes.
• Switch redirects from redirects.py/sphinx-reredirects style to redirects.txt + sphinx-rerediraffe, and move templates/static assets to Sphinx Stack layout.

Reviewed changes

Copilot reviewed 44 out of 50 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
doc/tutorial/single-member.md	Updates {terminal} directive usage (input/output-only formatting).
doc/tutorial/multi-member.md	Updates {terminal} directive usage (input/output-only formatting).
doc/reuse/substitutions.yaml	Adds centralized substitutions YAML (tracks current LTS/feature).
doc/requirements.txt	Introduces static Python requirements for docs tooling/extensions.
doc/reference/release-notes/release-notes-template.md	Clarifies template instructions for release note authors.
doc/redirects.txt	Adds redirects mapping file for sphinx-rerediraffe.
doc/redirects.py	Removes old Python redirects mapping.
doc/Makefile.sp	Removes starter-pack Makefile wrapper.
doc/Makefile	Replaces build/install/check targets to match Sphinx Stack conventions.
doc/how-to/update_upgrade.md	Updates {terminal} directive usage.
doc/how-to/snaps.md	Updates {terminal} directive usage.
doc/how-to/ovn_underlay.md	Updates {terminal} directive usage.
doc/how-to/member_remove.md	Improves terminology clarity (“monmap” → “monitor map”).
doc/how-to/ceph_networking.md	Updates {terminal} directive usage and formatting.
doc/explanation/security.md	Adds spelling exception markup for “man-in-the-middle”.
doc/explanation/initialization.md	Updates {terminal} directive usage; splits combined blocks.
doc/doc-cheat-sheet-myst.md	Updates terminal directive guidance and links to sphinx-terminal README.
doc/custom_conf.py	Removes legacy split config file (merged into conf.py).
doc/conf.py	Consolidates/updates Sphinx configuration for canonical-sphinx + Sphinx Stack.
doc/.wordlist.txt	Removes starter-pack wordlist file (moves to Vale approach).
doc/.sphinx/version	Records the Sphinx Stack version the docs were aligned to.
doc/.sphinx/spellingcheck.yaml	Removes pyspelling configuration (replaced by Vale).
doc/.sphinx/get_vale_conf.py	Reworks Vale config download script (clone + copy style guide assets).
doc/.sphinx/build_requirements.py	Removes dynamic requirements generator.
doc/.sphinx/_templates/sidebar/search.html	Removes legacy sidebar search template override (RTD search removed).
doc/.sphinx/_templates/page.html	Removes legacy page template override (moved to new templates layout).
doc/.sphinx/_templates/header.html	Removes legacy header template (moved to doc/_templates).
doc/.sphinx/_templates/404.html	Removes legacy 404 template (handled differently in new layout).
doc/.sphinx/_static/header.css	Removes legacy header styling (replaced by new static layout/CSS).
doc/.sphinx/_static/header-nav.js	Removes legacy header dropdown script.
doc/.sphinx/_static/github_issue_links.js	Removes legacy “Give feedback” JS injection.
doc/.sphinx/_static/github_issue_links.css	Removes legacy styling for feedback link.
doc/.sphinx/_static/furo_colors.css	Removes legacy Furo color overrides.
doc/.sphinx/_static/footer.js	Removes legacy footer contributors dropdown script.
doc/.sphinx/_static/footer.css	Removes legacy footer contributors styling.
doc/.sphinx/_static/custom.css	Removes legacy custom CSS bundle from old layout.
doc/.sphinx/_static/404.svg	Removes legacy 404 asset from old layout.
doc/.sphinx/_integration/rtd-search.js	Removes RTD search integration script.
doc/.sphinx/_integration/add_config.py	Updates integrated-build config injection (URLs/paths/tags).
doc/.readthedocs.yaml	Updates RTD build commands and requirements path.
doc/.gitignore	Updates ignores for new .venv and removed generated files.
doc/.custom_wordlist.txt	Adds “subfolders” to custom word list.
doc/_templates/header.html	Adds new header template in Sphinx Stack location with accessibility attributes.
doc/_templates/google-tag.html	Adds Google Tag Manager include template.
doc/_templates/footer.html	Updates footer template and adds license rendering section.
doc/_templates/base.html	Adds base template override for JS globals and theme style suppression.
doc/_static/microcloud_tag.png	Adds MicroCloud tag image asset.
doc/_static/favicon.png	Adds favicon asset.
.github/workflows/tests.yml	Sets docs job Python version to 3.12.

Comments suppressed due to low confidence (2)

doc/_templates/footer.html:47

• copyright in doc/conf.py already includes the author value, but the footer prints {{ copyright }} {{ author }}. This will duplicate the author text in the rendered footer. Either remove {{ author }} here or change the copyright string to exclude the author so it’s only rendered once.
  doc/_templates/footer.html:51
• Same duplication issue as above in the non-hasdoc('copyright') branch: {{ copyright }} {{ author }} will repeat the author because copyright already embeds it.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[roosterfish]

Thanks for this, I cannot say much about the doc tooling changes, but I have commented on a few items that caught my eye.

@elijahgreenstein could you please also have a look?

The last commit is causing a failure of the DCO test. I have just earlier merged your PR on link updates, you can now also rebase, maybe this helps.

[roosterfish]

Can we use 3.14? According to https://devguide.python.org/versions/ it seems to be latest stable one.

[roosterfish]

Just curious if this is a file that can be imported from somewhere else if there is a central place for it?
It doesn't look MicroCloud specific so I am wondering if this is feasible.

[minaelee]

It's a lightly refactored version from the Sphinx Stack, and identical to what LXD uses. In the future, it might be better to drop the refactoring (or suggest it in the Sphinx Stack) so that LXD and MicroCloud can both use the same version as the upstream.

[minaelee]

Note: RTD build has been failing for the past hour. I tried to debug it but nothing helped, and then I thought to check other projects with recent RTD builds, and it looks like every build within the past hour on RTD has failed. Could be a GitHub issue or RTD issue. Either way, I'll wait to see if it is resolved in the morning.

Also the link checks are quite unstable over the last days, lots of timeouts. Likely related to the recent issues?

Looks like the issues are resolved and the RTD build is working now. I'll drop that last commit that was failing the DCO check (it was just a test commit to try to refresh the RTD cache).

Re: linkchecks, at first it was due to the recent issues, but now I suspect that ubuntu.com has stiffer protections against non-browser requests.