feat(ci,docs): build and publish a combined HTML and spec doc artifact#2638
Open
danceratopz wants to merge 9 commits intoforks/amsterdamfrom
Open
feat(ci,docs): build and publish a combined HTML and spec doc artifact#2638danceratopz wants to merge 9 commits intoforks/amsterdamfrom
danceratopz wants to merge 9 commits intoforks/amsterdamfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## forks/amsterdam #2638 +/- ##
================================================
Coverage 86.25% 86.25%
================================================
Files 599 599
Lines 37032 37032
Branches 3795 3795
================================================
Hits 31943 31943
Misses 4525 4525
Partials 564 564
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
danceratopz
force-pushed
the
experiments/publish-docs
branch
from
53d81a0 to
950f232
Compare
Split HTML docs (`mkdocs`) and spec docs (`docc`) into parallel CI jobs that produce a combined artifact for `steel-website` deployment. - Add `docs-build.yaml` with five jobs: `check-should-publish`, `html-docs`, `spec-docs`, `combine`, and `trigger-aggregator`. - Add `.github/configs/docs-branches.yaml` branch allowlist. - Slim `test-docs.yaml` to changelog and markdown lint only (renamed to "Static Doc Checks"); the `mkdocs` build job moves to the new workflow. - Update `mkdocs.yml` `site_url` to read from `SITE_URL` env var with fallback to `steel.ethereum.foundation/docs/`. - Update `DocsConfig` URLs to `steel.ethereum.foundation/docs`.
Add `experiments/**` branch trigger and `experiments/publish-docs` to the allowlist so the full pipeline (including `combine` and `trigger-aggregator`) runs on push. Revert before merge.
Write a summary table with branch, event, deploy, and allowlist status. Include a callout explaining why artifacts will or will not be published.
danceratopz
force-pushed
the
experiments/publish-docs
branch
from
6485dc5 to
4dcd1d9
Compare
Intentionally not dropping original commits for transparency.
For `workflow_dispatch`, `github.sha` points at the launch ref (typically the default branch), not at the branch that `html-docs`/`spec-docs` actually check out via the `ref:` override. Published `metadata.json` and the `steel-website` dispatch payload therefore could reference a commit on a different branch than the one that was built. Resolve the tip SHA of the target branch in `check-should-publish` via `git ls-remote` and expose it as a job output. Consume that output in the `combine` metadata step and the `trigger-aggregator` dispatch.
The `edit_uri` value has no effect: mkdocs-material only renders the "edit this page" pencil when the theme feature `content.action.edit` is enabled, which this config does not enable. Drop the unused setting to avoid a stale reference to `forks/amsterdam` once docs are published for additional branches.
Previously the empty-allowlist branch wrote `should_publish=false` and exited 0, silently no-op'ing all downstream publishing. `exit 1` surfaces a misconfigured or missing `.github/configs/docs-branches.yaml` as a failed check instead.
danceratopz
added
A-doc
Member
Author
|
Successful artifact publish here: https://github.com/ethereum/execution-specs/actions/runs/24453695866 |
danceratopz
commented
Apr 15, 2026
| site_url: !ENV [SITE_URL, "https://steel.ethereum.foundation/docs/"] | ||
| repo_url: https://github.com/ethereum/execution-specs | ||
| repo_name: execution-specs | ||
| edit_uri: edit/forks/amsterdam/docs/ |
Member
Author
There was a problem hiding this comment.
We didn't have this "edit on click" feature enabled our config anyway, so this was redundant config. Would be nice, but not relevant here.
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.
Add a
docs-build.yamlworkflow that builds HTML docs (mkdocs) and spec docs (docc) in parallel, combines them into a single artifact, and triggers thesteel-websiteaggregator for deployment tosteel.ethereum.foundation/docs/.This replaces the mkdocs build job in
test-docs.yamland replacesgh-pages.yaml(follow-up issue to delete cf #2684).Changes:
.github/workflows/docs-build.yamlwith five jobs:check-should-publish,html-docs,spec-docs,combine, andtrigger-aggregator..github/configs/docs-branches.yamlbranch allowlist controlling which branches get published..github/workflows/gh-pages.yaml-- spec docs are now built bydocs-build.yamland served viasteel-website.test-docs.yamlto changelog and markdown lint only (renamed to "Static Doc Checks").mkdocs.ymlsite_urlto read fromSITE_URLenv var with fallback tosteel.ethereum.foundation/docs/.DocsConfigbase URL tosteel.ethereum.foundation/docs.On PRs, only the two build jobs run (testing the build). On push to allowlisted branches, the full pipeline runs: build, combine, upload artifact, and dispatch to
steel-website.Related Issues or PRs
gh-pages.yaml#2684✅ Checklist
just statictype(scope):.mkdocs servelocally and verified the auto-generated docs for new tests in the Test Case Reference are correctly formatted.Cute Animal Picture