Publish the documentation to GitHub Pages - #11
Merged
Merged
Conversation
A workflow builds the zdocs document set (doc/: the manual and the API reference) and publishes it at https://tiacsys.github.io/zdocs/. A pull request builds and checks only. A push to main, or a manual run on main, also deploys. The site root is deploy/html/, as deploy-layout.rst and ADR 0012 describe, with a landing page next to the documents. This document set has no Doxygen document, so the Doxygen cross-document navigation is not in the site. New files: * .github/workflows/docs.yml: actions pinned by commit SHA, Doxygen 1.16.1 from the release binary, checked by hash and cached. Read-only permissions, except pages and id-token in the deploy job. * .github/scripts/check_site.py: every href and src of the assembled site must resolve to a file in the site, and a #fragment to an id. * doc/west.yml: the workspace for CI, Zephyr v4.4.1 only. The build needs Zephyr as a CMake package and for its doc/_extensions. * doc/requirements-ci.txt: every Python package pinned, also the indirect ones. sphinx-needs is 8.3.0, the reference version. Pygments stays at 2.20.0: with 2.21.0, doccheck reads a pattern in highlighted code as a dead link. * doc/site/index.html: the landing page. Gates after the build: doc-check, zero warnings in the stage-two logs, the link check, and an audit for local paths, addresses and tokens. Checked locally in a west workspace like the CI one, with a new venv from the lock: doc-check OK, 0 warnings, 71 pages and 3626 internal links with 0 broken, audit clean, and an HTTP crawl of the site under /zdocs/ with 0 failures. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
The engine pinned sphinx-needs 8.1.1. The working environments of the zdocs consumers (the safety docset, the safety toolbox) and the CI lock of the documentation workflow use 8.3.0, the reference version. The engine pin now matches, so doc/requirements-ci.txt no longer lists an exception. Checked with a new venv from doc/requirements-ci.txt: the unit suite passes (147), the docs build has doc-check OK and 0 warnings, the site check and the HTTP crawl find 0 broken links. The zdocs-tests acceptance suite gives the same result as at origin/main (273 passed; the failures are the steps that need unmerged engine changes). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds the zdocs documentation (the manual and the API reference in
doc/) with GitHub Actions, and publishes it to GitHub Pages at https://tiacsys.github.io/zdocs/.main, or a manual run onmain, also deploys.deploy/html/, asdeploy-layout.rstand ADR 0012 describe, with a landing page next to the documents.doc-check, zero warnings in the stage-two logs, a link check of the assembled site (.github/scripts/check_site.py), and an audit for local paths, addresses and tokens.doc/requirements-ci.txt.doc/west.ymlgives CI a workspace with Zephyr v4.4.1 only.This PR is independent of the stack #4–#9: it touches none of its files.
Testing
Locally, in a west workspace like the CI one, with a new venv from the lock: doc-check OK, 0 warnings, 71 pages with 3626 internal links and 0 broken, audit clean, and an HTTP crawl of the site under
/zdocs/with 0 failures. Unit suite: 147 passed. The zdocs-tests acceptance suite gives the same result as atmain.One-time setting
Settings › Pages › Source = "GitHub Actions". Without it, the deploy job fails; the build job still runs.
🤖 Generated with Claude Code