Optimize Quarto build: remove R, cache Python docs, exclude _source, scope lightbox

[nibalizer]

Pull Request Description

What and why?

The Quarto docs build takes ~23 minutes. This PR applies 6 optimizations to dramatically reduce build time:

1. Remove R setup — R + 4 R packages are installed on every build, but zero .qmd files use {r} code blocks. Pure waste (~2-3 min saved).
2. Cache Python API docs by library SHA — The full validmind-library is installed via Poetry and 183 .qmd files are generated every build. Now cached and skipped on cache hit (~5-8 min saved).
3. Cache Quarto site output — _site/, _freeze/, and .quarto/ are cached with config-aware keys so incremental renders are faster on subsequent runs.
4. Add execute: false + freeze: true globally — No execute/freeze config existed, risking accidental notebook execution during render.
5. Exclude _source/ from Quarto project scan — 3 repos are cloned inside the Quarto project dir; Quarto was walking/scanning all their files unnecessarily.
6. Disable lightbox: true globally — Was enabled on all ~660 pages but only 21 actually use it. Now enabled only where needed (via training/_metadata.yml and 2 individual page frontmatters).

All 3 deploy workflows (prod, staging, PR preview) are updated consistently.

How to test

1. Open this PR — the validate-docs-site workflow will run with all optimizations
2. Compare the workflow duration against the previous ~23 min baseline
3. First run will be a cold cache (full build), but should still be faster due to R removal + _source exclusion + lightbox scoping
4. Push a follow-up commit to the same PR to see the warm-cache benefit
5. Verify the PR preview site renders correctly with lightbox working on training pages

What needs special review?

• The execute: false + freeze: true change — confirm no pages currently rely on live code execution during render (audit found 0 {r}, {python}, or {julia} blocks in any .qmd files)
• The lightbox: false global default — verify training pages and the 2 individual pages (conventions.qmd, 2024-dec-06/release-notes.qmd) still show lightbox correctly

Dependencies, breaking changes, and deployment notes

• No breaking changes — all optimizations are backwards compatible
• First build after merge will be a cold cache; subsequent builds benefit from caching
• The _source/ exclusion via render: ["!_source/"] means Quarto won't attempt to render files in that directory (they were never meant to be rendered directly anyway)

Release notes

Internal build performance improvement — no user-facing changes.

Checklist

• What and why
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• Tested locally

[github-actions]

PR Summary

This pull request introduces enhancements to the documentation deployment pipelines by adding caching mechanisms to improve build performance. Specifically, the changes add new steps in three GitHub Actions workflows (for production, staging, and validation) to:

1. Retrieve the current SHA of the validmind-library, which is then used to generate the cache key for the Python library docs.
2. Cache the generated Python library docs so that if the underlying content has not changed (detected by the SHA), the Poetry installation and doc generation steps are skipped.
3. Cache the output of the Quarto site (including the site’s rendered output and configuration files) using a key generated from multiple relevant file hashes.

Additionally, the pull request makes updates to the Quarto configuration files to adjust the render rules and toggle the lightbox feature (disabling it globally in one config while enabling it in specific pages) and fixes a minor inconsistency in the documentation README file.

These improvements aim to reduce build times by reusing cached resources and ensuring that documentation output is only regenerated when necessary.

Test Suggestions

• Trigger the production, staging, and validation workflows and verify that caching works as expected by checking the logs for cache-hit and cache-miss messages.
• Modify files in the validmind-library directory and ensure that the cache key changes, thereby invalidating old caches and forcing regeneration.
• Test rendering the docs site locally to confirm that the modified Quarto render and lightbox settings behave as intended.
• Review changes in the README and Quarto configuration files to ensure that documentation is still building and displaying correctly.

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: 9beb601

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.42	1.00	0.82
/get-started/get-started.html	0.85	0.68	1.00	0.73
/guide/guides.html	0.85	0.68	1.00	0.82
/index.html	0.93	0.68	1.00	0.82
/releases/all-releases.html	0.86	0.68	1.00	0.73
/support/support.html	0.91	0.68	1.00	0.82
/training/training.html	0.85	0.70	0.96	0.73

[nrichers]

I much appreciate the idea of making our Quarto renders faster, so thank you for this PR in principle. 💖.

I need to scrape out recently added but unused media out of the release-notes repo history with filter-repo again as it's skewing build times, but not building the Python docs every time seems to shave off about 2' 30". Nice!

Cache Quarto site output — _site/, _freeze/, and .quarto/ are cached with config-aware keys so incremental renders are faster on subsequent runs.

Given this saves all of 6", I would be inclined to remove this part or we need to test more. There is a known limitation for incremental renders with quarto preview where updated _*.qmd files and pages with listings are not re-rendered on update but I'm not sure how your workflow changes would behave here.

The lightbox: false global default

This breaks the release notes where we currently let users expand thumbnails of screenshots (26.03 PR example vs 26.03 prod example). We either need to allow lightbox for release notes or undo this change.

The _source/ exclusion via render: ["!_source/"] means Quarto won't attempt to render files in that directory

AFAIK, Quarto automatically ignores files and directories that start with _ unless explicitly embedded, so I don't think this change does anything?

(FYI, the validate workflow in this PR required Beck's changes in main that removed our old breaking changes page (the one that had the R dependency), should be sorted now.)