feat: publish /docs/ from FastLED/dox build output #9
Description
Context
Serve documentation directly at https://fastled.io/docs/ by pulling the generated output from FastLED/dox. This avoids browser redirects and keeps hosting on GitHub Pages with the existing DNS.
Verified current behavior:
- The site's publishing workflow archives tracked website files into
_siteand deploys that artifact. It does not import documentation. /docs/serves an HTML redirect;/docs/annotated.htmlreturns HTTP 404, whilehttps://fastled.github.io/dox/annotated.htmlreturns HTTP 200.- Dox builds the exact FastLED release tag and publishes generated HTML through Pages artifacts, keeping it out of Git history. Its current
github-pagesartifact has one-day retention, so it cannot be the sole download source for later website deployments.
Proposal
- Expose a durable, versioned download of the successfully published dox output, with a small manifest identifying the release tag, source commit, publication generation, and bundle checksum. Coordinate the producer-side change in
FastLED/doxas needed. - Extend the existing website publishing workflow to fetch that output and stage its root under
_site/docs/, replacing the redirect landing page. Include all generated HTML, search files, stylesheets, scripts, and images. - Refresh the website copy after successful upstream documentation publication. Compare publication identity/digest so unchanged checks skip deployment; intentional upstream rebuilds of the same tag must also be detectable. Ordinary website deployments must retain the latest successful docs copy.
- Fail before deployment if the bundle cannot be obtained or validated, preserving the currently published site.
Acceptance criteria
- Demonstrate RED → GREEN: the current
/docs/annotated.htmlrepro fails with 404; after implementation,/docs/, a real nested API page, and representative README-linked guides return HTTP 200 with documentation content without HTML/JavaScript redirects. - Mirrored
release.jsonmatches the upstream release tag and source SHA; documentation is generated only in dox from the exact tag, never rebuilt from a subsequentmasterref by this repository. - Navigation, search, relative links, styles, and scripts work beneath
/docs/. - A new upstream publication updates the mirror; an unchanged check causes no docs-driven site deployment. Verify same-tag intentional rebuilds are detected.
- A fresh website deployment can retrieve the docs after the short-lived Actions artifact has expired. A failed import leaves the live site intact.
- Homepage, PaletteKnife, blog, and other existing website assets remain functional.
- Generated documentation is never committed to this repository or
FastLED/FastLED; DNS and hosting remain on GitHub Pages.https://fastled.github.io/dox/remains available.
Decisions
- This issue belongs in the website repository because it owns the combined Pages deployment; dox remains the documentation build source of truth.
- Publish a second served copy under
/docs/to support existing URLs directly, without requiring Vercel, Cloudflare, or a DNS migration. - Reuse the existing publishing workflow; daily checks may inspect state but must not unconditionally republish documentation.
- Choose the durable bundle delivery and cross-repository notification mechanism during implementation; account for artifact expiry, least-required token permissions, and recovery when a notification is missed.
Related work
- chore: prepare HTTP documentation redirects #8 proposes Vercel HTTP redirects; direct publication is an alternative to that approach. Reconcile that PR when this solution is verified.
- FastLED/FastLED#4878: original documentation migration and Git history cleanup.
Activity
zackees commentedon Oct 22, 2026
Implemented and deployed through FastLED/dox#8, #10, and #11.
Live verification
/docs/annotated.htmlrepro changed from HTTP 404 to HTTP 200./docs/, the nesteddd/dbb/class_c_fast_l_e_d.htmlAPI page, and all 11 README-linked guide pages return documentation directly without redirects.d7402f1294e4548d9f8317f76afad37afaddb237, Doxygen 1.13.2. This website imports the generated bundle; it does not check out FastLED or run Doxygen.CFastLEDopened the nested API page under/docs/with HTTP 200 and no JavaScript errors. Seventeen representative documentation pages/assets match upstream byte for byte.Publication behavior
39728951124-1to39729808961-1while retaining the exact same release tag/source SHA. The site check detected and deployed it; the new generation is verified live at both origins.Delivery and maintenance
Validation: 18 dox tests, 11 site tests, Ruff, Actionlint, cross-repository package/import verification, primary code review, and the live checks above passed. GitHub Pages can briefly serve a previous manifest during cache propagation; daily checks converge on the current generation.
zackees commentedon Oct 22, 2026
Final immediate-check stress verification exposed a GitHub Pages cache race: a runner saw an older upstream publication after the newer site mirror was live and imported it. Reopening while adding a backwards-generation guard and restoring the newest publication.
zackees commentedon Oct 22, 2026
Cache-race follow-up completed in #12. The importer now compares numeric publication generations and fails before deployment when the upstream manifest is older than the valid deployed marker. The actual HTTP regression failed before the fix and passes afterward; all 11 site tests, Ruff checks, and primary review pass.
Restoration deployment succeeded using generation
39729808961-1. A fresh public audit confirms both publication manifests and release metadata match, all 17 sampled documentation pages/assets are byte-identical to upstream, and the five existing website asset hashes remain unchanged. Closing with the newest generation restored and verified live.