Documentation¶

The execution-specs documentation is generated via Zensical and hosted at steel.ethereum.foundation/docs/execution-specs/. The site is configured in zensical.toml.

Prerequisites¶

uv sync

Build and Verify the Documentation¶

One time build in strict mode (fails on warnings, including broken internal links and anchors):

just docs

The site is written to .just/docs/site. just docs-fast only generates part of the Test Case Reference (tests/frontier plus the test modules linked from other pages) for faster iteration.

Run all docs related checks:

just spellcheck
just lint-md
just docs

Local Deployment and Test¶

Serve the site locally with live reload on changes to docs/**/*.md:

just docs-serve        # full Test Case Reference
just docs-serve-fast   # partial Test Case Reference, faster iteration

Generated pages are not regenerated while serving; re-run just docs-gen (or just docs-gen --fast) in another terminal after changing tests or fill options.

For more help, see the gen_test_doc pytest plugin's documentation:

A pytest plugin that generates test case documentation for the docs site.

It generates the top-level "Test Case Reference" section of the Zensical documentation site.

Note:¶

Pages are written as plain Markdown files below --gen-docs-output-dir (default: docs), underneath docs/tests. The section's navigation is written to docs/tests/navigation.md, a nested literate-nav file that docs/navigation.md links to via [Test Case Reference](tests/).
docs/tests is gitignored and is recreated by docs/scripts/gen_docs.py.

Usage:¶

To generate the pages (and the other generated docs pages), run:

uv run python docs/scripts/gen_docs.py

Or to build and view the site:

just docs-serve

Implementation¶

Generated Pages¶

Some pages are not tracked in git; docs/scripts/gen_docs.py (just docs-gen, run by all just docs* recipes) writes them into docs/ before the site is built:

getting_started/contributing.md and getting_started/security.md: copies of the repository's CONTRIBUTING.md and SECURITY.md.
filling_tests/filling_tests_command_line_options.md: the output of fill --help.
tests/: the "Test Case Reference" (see below).

These paths are listed in .gitignore.

Plugins and Extensions¶

The site uses Zensical's built-in replacements of the following MkDocs plugins (configured in zensical.toml):

mkdocstrings and mkdocstrings-python: To generate documentation from Python docstrings (Zensical integrates these packages, which must be installed).
literate-nav: Defines the navigation in docs/navigation.md.
glightbox: For improved image and inline content display.
social: Generates social cards.

The mkdocs-click Markdown extension documents the CLIs.

The "Test Case Reference" Section¶

This section is generated by the gen_test_doc pytest plugin, run by docs/scripts/gen_docs.py. It generates a sequence of nested pages of all Python modules detected under ./tests. Each page contains a stub to the doc generated by mkdocstrings from the module's docstrings and source code.

No action is necessary if a new test directory or module is added to ./tests, it will be picked up automatically.

All pages that are to be included in the documentation and the navigation bar must be included in docs/navigation.md, except "Test Case Reference" entries. docs/navigation.md links to the tests/ directory; the nav entries of the "Test Case Reference" are generated into docs/tests/navigation.md, which literate-nav reads as a nested navigation file.