[Amaury Chamayou (achamayou)]

Motivation

Improve the documentation experience across diagram rendering, responsive landing pages, language navigation, and multi-version publishing.
This is broader than a renderer replacement: it modernizes the documentation stack, reduces custom styling, makes application guides easier to discover, and improves consistency across section landing pages.

Implementation summary

• Replace sphinxcontrib-mermaid with sphinx-pele==0.1.0, using default rendering options, bundled assets, and native light/dark theme support while retaining Mermaid directives.
• Upgrade compatible Sphinx dependencies and replace incompatible sphinx-panels cards with responsive sphinx-design grids.
• Reduce custom CSS to tile-image sizing and spacing; remove decorative fixed diagram colors while preserving primary-node and enclave-key annotations.
• Add a bundled, attributed Rust logo linked to the experimental Rust application guide and use it on the Build Apps landing page.
• Standardize action-led card descriptions, language ordering, terminology, and icon names; add landing-page cards for Logging and Cryptography API documentation already present in the sidebar.
• Build published versions from their own Git snapshots in separate Python environments, preserving historical dependencies and shared version navigation.
• Preserve the GitHub footer link with current Furo, make edit links target the displayed documentation version instead of always main, and document local/publishing requirements.

Safety and compatibility

Documentation-only: no CCF runtime, consensus/KV, API, ledger-format, mixed-version operation, or recovery changes.
Archived versions retain their original renderer and card extension rather than being built with the new configuration.
Sphinx is constrained below 9 because sphinx-multiversion still uses the older configuration API.

Validation: the full warnings-as-errors Sphinx build and all 16 scripts/ci-checks.sh checks pass.
Browser checks cover all 52 diagrams and all nine converted landing pages across desktop/mobile and light/dark themes, without JavaScript errors, including the linked Rust logo.
Additional checks verify language ordering, Logging/Cryptography card coverage, and edit links for both main and release/7.x.
The isolated publisher was also validated against a committed snapshot, and a modern/legacy integration fixture verifies both renderers and bidirectional version links.

[Copilot]

🔵 Needs a closer look

Historical-build and navigation compatibility remain unverified because archived-ref configurations and dependencies are unavailable in this snapshot, requiring a full publish against the actual selected refs.

No open issues 🎉

What changed in this PR

Migrates CCF documentation diagrams to Pele for bundled rendering and light/dark theme support, while preserving historical documentation builds. No CCF runtime behavior changes.

Changes:

• Replaces Mermaid-specific dependencies and styling, adjusts diagram readability, and preserves the GitHub footer link.
• Converts nine landing pages from panels to responsive sphinx-design grids.
• Adds isolated, per-version publishing from Git snapshots with shared version navigation and documents build requirements.

Custom instructions used: No additional repository instruction files were loaded.

File	Description
scripts/​build-docs.py	Builds version snapshots in separate Python environments.
doc/​use_apps/​index.rst	Converts user documentation cards to grids.
doc/​requirements.txt	Adds Pele and sphinx-design; updates Sphinx constraints.
doc/​overview/​index.rst	Converts overview cards to grids.
doc/​operations/​index.rst	Converts operations cards to grids.
doc/​operations/​data_persistence.rst	Improves diagram label contrast.
doc/​operations/​code_upgrade.rst	Improves contrast on fixed-fill diagram nodes.
doc/​index.rst	Converts main navigation cards to grids.
doc/​governance/​index.rst	Converts governance cards to grids.
doc/​contribute/​index.rst	Converts contributor cards to grids.
doc/​contribute/​build_ccf.rst	Documents Python requirements and isolated publishing.
doc/​conf.py	Enables Pele and sphinx-design; configures sequence spacing.
doc/​build_apps/​index.rst	Converts application development cards to grids.
doc/​audit/​index.rst	Converts audit cards to grids.
doc/​architecture/​index.rst	Converts architecture cards to grids.
doc/​architecture/​cryptography.rst	Replaces diagram icons with borders and updates the legend.
doc/​_templates/​page.html	Adapts the GitHub footer link to current Furo markup.
doc/​_static/​css/​custom.css	Removes Mermaid dark-theme background overrides.
.github/​workflows/​doc.yml	Uses the isolated documentation publisher.

_{Review effort: Balanced}