Skip to content

Documentation

The execution-specs documentation is generated via mkdocs and hosted at steel.ethereum.foundation/docs/execution-specs/.

Prerequisites

uv sync

Build and Verify the Documentation

One time build in strict mode:

just docs

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 or tests/**/*.py:

just docs-serve        # full build
just docs-serve-fast   # skips the Test Case Reference, faster iteration

For more help (including ensuring a clean build), see the gen_test_doc pytest plugin's documentation:

A pytest plugin that generates test case documentation for use in mkdocs.

It generates the top-level "Test Case Reference" section in EEST's mkdocs site.

Note:

  • No output directory is specified for the generated output; file IO occurs via the mkdocs-gen-files plugin. mkdocs serve writes intermediate files to our local docs/ directory and then copies it to the site directory. We modify docs/navigation.md and write all other output underneath docs/tests. If mkdocs is interrupted, these intermediate artifacts are left in docs/.

Usage:

Ensuring a clean build

In case mkdocs has polluted the docs/ directory with intermediate files, run:

git restore docs/navigation.md  # Careful if you have local modifications!
rm -rf docs/tests docs/docs site

To test doc generation, run the plugin without mkdocs:

uv run fill -p pytest_plugins.filler.gen_test_doc.gen_test_doc --gen-docs     --fork=<fork> tests

Or to build and view the site:

uv run mkdocs serve

Implementation

Plugins

The documentation flow uses mkdocs and the following additional plugins:

The "Test Case Reference" Section

This section is auto-generated via a combination of:

  1. mkdocstrings and mkdocstrings-python,
  2. mkdocs-gen-files,
  3. mkdocs-literate-nav.

It auto-generates a sequence of nested pages (with nav entries) 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. The mkdocs-gen-files and mkdocs-literate-nav plugins were created exactly for this purpose.

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

Working with generated content

The files in the ./tests directory are watched by mkdocs serve. Run mkdocs serve and edit the source docstrings: The browser will reload with the new content automatically.

All pages that are to be included in the documentation and the navigation bar must be included in navigation.md, except "Test Case Reference" entries. This is enabled by mkdocs-literate-nav. The nav entries for the automatically generated "Test Case Reference" section are generated in mkdocs-gen-files and appended to navigation.md.

Current nav ordering limitations

The "Test Case Reference" section must currently be the last section in the nav. This is because our mkdocs flow:

  1. Reads navigation.md.
  2. Generates the Test Case Reference documentation and appends the Test Case Reference entries to navigation.md
  3. Generates the nav.

If necessary, we could probably split navigation.md into two files

  • navigation-pre-test-case-reference.md,
  • navigation-post-test-case-reference.md,

and create an arbitrary ordering in the Test Case Reference doc gen script. But this is untested.