Concept for versioned HTML doc and rendered specification

[danceratopz]

Background and Top-Level Goal

The execution-specs repo manages the implementation of multiple Ethereum forks in parallel via separate git branches, for example:

• forks/osaka (default branch),
• forks/amsterdam,
• eips/amsterdam/eip-7928.

Goal

In order to support the developer community working on Scheduled For Inclusion (SFI'd) versions (or other substantial efforts), the execution-specs HTML pages should provide versioned sites matching each of these larger development efforts. I.e., the HTML pages should contain a version that corresponds to one of these branches. The docs of each branch are not to be versioned; they will reflect the HEAD of each branch.

Status Quo Prior to The Weld

Repository	Branch Strategy	Docs Content	Versioned	URL (with version example)
execution-specs	Maintains fork-specific code in corresponding branches (e.g., forks/amsterdam)	Rendered EELS spec (from Python source)	No, generated from default branch	https://ethereum.github.io/execution-specs/
execution-spec-tests	Aimed to merge all fork-specific code to main	Developer doc, Test Case Reference	Yes (per test fixture release)	https://eest.ethereum.org/v5.0.0/

An important part of this documentation (originally in EEST) is the "Test Case Reference", e.g., for the v5.0.0 release, which becomes branch-dependent post-Weld. These are HTML pages, included in the mkdocs generated site, generated from the tests/ test module docstrings and metadata that contain:

• An overview of all test cases, organized by fork and EIP or target area, e.g., benchmarks; the structure reflects the structure of the tests/ directory. The individual test pages (attempt to) visualize the parameter combinations that each test uses. This information is extracted from the docstrings and the test parameters via a custom plugin.
• For newer, EIP-specific test folders: An EIP Checklist, which displays the current progress made in testing this EIP and which tests have been implemented and which are outstanding.

While the developer docs will mainly be fork-agnostic (although new features may need to be documented in the guides on "Writing Tests", for example), the Test Case Reference is now, as part of execution-specs, heavily branch dependent.

Suggestion for Versioning

The HEAD of every branch that has a ongoing substantial implementation effort will be included as a version that can be selected on the documentation page. In this manner, the available tests for each fork, respectively EIP, can be browsed corresponding to its branch.

Branch	Docs URL	Spec URL
forks/osaka	/forks/osaka/	/forks/osaka/spec/
forks/amsterdam	/forks/amsterdam/	/forks/amsterdam/spec/
eips/amsterdam/eip-7928	/eips/amsterdam/eip-7928/	/eips/amsterdam/eip-7928/spec/

The base URL can initially be the Github pages: https://ethereum.github.io/execution-specs/, but preferably be steel.ethereum.foundation/docs/.

Implementation Idea (only for top-level version selector)

Each actively developed branch (e.g. a fork or major EIP) builds its own MkDocs + spec output and uploads it as a zipped artifact.
A single aggregator workflow on the default branch then downloads the latest artifacts from all allow-listed branches, unpacks them into subpaths matching their branch names (e.g. /forks/osaka/, /eips/amsterdam/eip-7928/), mirrors the default branch to the site root (/ and /spec/), generates a versions.json manifest for the UI dropdown, and publishes the combined result as one GitHub Pages site.