Skip to content

refactor(docs): port entire documentation from mkdocs to hugo #1899

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
Empty file added docs/.hugo_build.lock
Empty file.
5 changes: 5 additions & 0 deletions docs/archetypes/default.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true
+++
80 changes: 73 additions & 7 deletions docs/CHANGELOG.md → docs/content/main/CHANGELOG.md

Large diffs are not rendered by default.

8 changes: 8 additions & 0 deletions docs/content/main/dev_docs/coding_style.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
+++
title = 'Coding Style'
weight = 25
+++

{{< callout warning "Documentation Moved" >}}
This documentation has been relocated to [Getting Started -> Code Standards](../getting_started/code_standards.md). Please use the new location for the most up-to-date information.
{{< /callout >}}
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Managing Configurations
+++
title = 'Managing Configurations'
weight = 5
+++

Configurations are managed by the `config` package. It provides both environment and application configurations.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,27 +1,30 @@
# EEST Dependency Management and Packaging
+++
title = 'Dependency Management and Packaging'
weight = 45
+++

EEST uses [`uv`](https://docs.astral.sh/uv/) to manage and pin its dependencies.

Please use `uv>=0.7.0` to ensure `uv` writes `uv.lock` files with consistent fields and formatting (see [ethereum/execution-spec-tests#1597]https://github.com/ethereum/execution-spec-tests/pull/1597).
Please use `uv>=0.7.0` to ensure `uv` writes `uv.lock` files with consistent fields and formatting (see [ethereum/execution-spec-tests#1597](https://github.com/ethereum/execution-spec-tests/pull/1597)).

## Managing Dependencies

We aim to provide specific [version specifiers](https://peps.python.org/pep-0440/#version-specifiers) for each of our direct and extra dependencies.

!!! note "Packages should be managed via `uv`"
{{< callout info "Packages should be managed via `uv`" >}}
Dependencies should be managed using `uv` on the command-line to ensure that version compatibility is ensured across all dependencies and that `uv.lock` is updated as required.

Dependencies should be managed using `uv` on the command-line to ensure that version compatibility is ensured across all dependencies and that `uv.lock` is updated as required.
The docs below cover common operations, see the `uv` [documentation on managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#multiple-sources) for more information.
{{< /callout >}}

The docs below cover common operations, see the `uv` [documentation on managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#multiple-sources) for more information.
{{< callout info "Separate PRs are preferred when managing dependencies" >}}
An upgrade of all pinned dependencies in `uv.lock` must be performed in a dedicated PR!

!!! info "Separate PRs are preferred when managing dependencies"
For other dependency changes, they can be included in the PR that removed use of the library, for example. But if a version bump is made, without related source code changes, it should be done in a dedicated PR. This makes the change:

An upgrade of all pinned dependencies in `uv.lock` must be performed in a dedicated PR!

For other dependency changes, they can be included in the PR that removed use of the library, for example. But if a version bump is made, without related source code changes, it should be done in a dedicated PR. This makes the change:

- Easier to track.
- Trivial to revert.
- Easier to track.
- Trivial to revert.
{{< /callout >}}

### Adding/modifying direct dependencies

Expand All @@ -45,17 +48,17 @@ ethereum-spec-evm-resolver = { git = "https://github.com/petertdavies/ethereum-s
...
```

!!! example "Example: Updating direct dependencies"

Example of a package dependency update:
```console
uv add "requests>=2.31,<2.33"
```
{{< callout info "Example: Updating direct dependencies" >}}
Example of a package dependency update:
```console
uv add "requests>=2.31,<2.33"
```

Example of a source dependency update:
```console
uv add "ethereum-spec-evm-resolver @ git+https://github.com/petertdavies/ethereum-spec-evm-resolver@623ac4565025e72b65f45b926da2a3552041b469"
```
Example of a source dependency update:
```console
uv add "ethereum-spec-evm-resolver @ git+https://github.com/petertdavies/ethereum-spec-evm-resolver@623ac4565025e72b65f45b926da2a3552041b469"
```
{{< /callout >}}

### Adding/modifying optional dependencies

Expand All @@ -74,11 +77,11 @@ docs = [
]
```

!!! example "Example: Updating an optional dependency"

```
uv add --optional lint "types-requests>=2.31,<2.33"
```
{{< callout info "Example: Updating an optional dependency" >}}
```
uv add --optional lint "types-requests>=2.31,<2.33"
```
{{< /callout >}}

## Upgrading Pinned Dependencies in `uv.lock`

Expand Down
36 changes: 36 additions & 0 deletions docs/content/main/dev_docs/docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
+++
title = 'Documentation'
weight = 15
+++

The `execution-spec-tests` documentation is generated via [`hugo`](https://github.com/gohugoio/hugo) and hosted remotely on Github Pages at [eest.ethereum.org](https://eest.ethereum.org/).

## Prerequisites

Grab the latest `hugo` binary from the official release page or build it yourself. Then make the binary executable and add it to the PATH (or to a directory that has already been added to the PATH like e.g. `/usr/local/bin/`). We do not require any additional plugins or dependencies.

## Build and Locally Host the Documentation

Build the docs:

```console
hugo
```

If you want to build + locally host the docs:

```console
hugo server
```

## Remote Deployment and Versioning

The execution-specs-test docs are hosted using Github pages at [eest.ethereum.org](https://eest.ethereum.org/). Versions are updated/deployed automatically as part of Github Actions.

### CI/CD: Doc Deployment via Github Actions

This is our workflow that automatically deploys updated/new versions of the docs:

| Workflow `yaml` File | What | When |
|----------------------|------|------|
| `docs.yaml` | Deploy new version of docs
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Documenting CLIs
+++
title = 'Documenting CLI Commands'
weight = 20
+++

EEST command line interfaces (CLIs) are documented using the [`click`](https://click.palletsprojects.com) library's built-in help system and the [`mkdocs-click`](https://github.com/mkdocs/mkdocs-click) extension for mkdocs. This allows generation of CLI documentation directly from the (click) source code, ensuring that the documentation is always up-to-date with the code.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Working with EEST Libraries Interactively
+++
title = 'Interactive Library Usage'
weight = 10
+++

You can work with EEST Python packages interactively with `ipython` using:

Expand All @@ -8,16 +11,16 @@ uvx --with-editable . ipython

This command will create a virtual environment, install EEST's packages in "[editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)" (source changes get reflected in the interactive shell), and start an `ipython` shell. You can then import any of the packages and experiment with them interactively.

!!! example "Example: Working with `ethereum_test_forks`"
{{< callout info "Example: Working with `ethereum_test_forks`" >}}
See which defined forks are "ignored" by default:

See which defined forks are "ignored" by default:

```python
from ethereum_test_forks import forks, get_forks
forks = set([fork for fork in get_forks() if fork.ignore()])
print(forks)
# -> {MuirGlacier, ArrowGlacier, GrayGlacier}
```
```python
from ethereum_test_forks import forks, get_forks
forks = set([fork for fork in get_forks() if fork.ignore()])
print(forks)
# -> {MuirGlacier, ArrowGlacier, GrayGlacier}
```
{{< /callout >}}

## Required `ipython` Configuration

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Logging
+++
title = 'Logging'
weight = 30
+++

This document describes the logging system used in the Ethereum Execution Spec Tests project. Currently, logging is only supported for `consume` commands.

Expand Down
11 changes: 10 additions & 1 deletion docs/dev/index.md → docs/content/main/dev_docs/main.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
# Developer Documentation
+++
title = 'Developer Documentation'
date = 2025-07-09T12:42:33Z
draft = false
[menu]
[menu.main]
name = 'Developer Doc'
weight = 25

+++

This documentation is aimed at `execution-spec-tests` developers:

Expand Down
16 changes: 10 additions & 6 deletions docs/dev/precommit.md → docs/content/main/dev_docs/precommit.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Enabling Pre-Commit Checks
+++
title = 'Enabling Pre-Commit Checks'
weight = 35
+++

There's a [pre-commit](https://pre-commit.com/) config file available in the repository root (`.pre-commit-config.yaml`) that can be used to enable automatic checks upon commit - the commit will not go through if the checks don't pass.

Expand All @@ -8,9 +11,10 @@ To enable pre-commit, the following must be run once:
uvx pre-commit install
```

!!! note "Bypassing pre-commit checks"
Enabling of pre-commit checks is not mandatory (it cannot be enforced) and even if it is enabled, it can always be bypassed with:
{{< callout info "Bypassing pre-commit checks" >}}
Enabling of pre-commit checks is not mandatory (it cannot be enforced) and even if it is enabled, it can always be bypassed with:

```console
git commit --no-verify
```
```console
git commit --no-verify
```
{{< /callout >}}
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Running Github Actions Locally
+++
title = 'Running Github Actions Locally'
weight = 40
+++

The Github Actions workflows can be tested locally using [nektos/act](https://github.com/nektos/act) without pushing changes to the remote. The local repository state will be used in the executed workflow.

Expand Down Expand Up @@ -27,12 +30,13 @@ The Github Actions workflows can be tested locally using [nektos/act](https://gi

or use one of the [other available methods](https://nektosact.com/installation/index.html).

!!! note "Updating nektos/act to the latest version via the Github CLI"
The `act` tool can be updated via the Github CLI:
{{< callout info "Updating nektos/act to the latest version via the Github CLI" >}}
The `act` tool can be updated via the Github CLI:

```bash
gh extension upgrade nektos/act
```
```bash
gh extension upgrade nektos/act
```
{{< /callout >}}

## Listing the Available Workflows

Expand Down
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
# Debugging Transition Tools
+++
title = 'Debugging Transition Tools'
+++

There are two flags that can help debugging `t8n` tools or the execution-spec-tests framework:

1. `--evm-dump-dir`: Write debug information from `t8n` tool calls to the specified directory.
1. `--evm-dump-dir` (Default: <repo>/logs/evm): Write debug information from `t8n` tool calls to the specified directory.
2. `--traces`: Collect traces of the execution from the transition tool.
3. `--verify-fixtures`: Run go-ethereum's `evm blocktest` command to verify the generated test fixtures.

## EVM Dump Directory

The `--evm-dump-dir` flag tells the framework to write the inputs and outputs of every call made to the `t8n` command to the specified output directory. The aim is to help debugging or simply understand how a test is interacting with the EVM. Debug output is only generated when this flag is explicitly specified.
The `--evm-dump-dir` flag tells the framework to write the inputs and outputs of every call made to the `t8n` command to the specified output directory. The aim is to help debugging or simply understand how a test is interacting with the EVM. The default location is `logs/evm` in the project root.

Each test case receives its own sub-directory under the `--evm-dump-dir` that contains these files which can be easily accessed from the HTML test report generated by `fill` (located by default in the root of the `--output` directory).

Expand Down Expand Up @@ -169,13 +171,10 @@ where the `verify_fixtures.sh` script can be used to reproduce the `evm blocktes
--single-fixture-per-file
```

!!! note "Execution scope of `evm blocktest`"
{{< callout info "Execution scope of `evm blocktest`" >}}
Note, by default, that `evm blocktest` is not executed per parametrized test case, but rather per test function. This is because each fixture JSON file contains fixtures for all the parametrized test cases for one test function. This means only one error will be reported, even if multiple fixtures fail within one fixture file.

Note, by default, that `evm blocktest` is not executed per parametrized test case, but rather per test function. This is because each fixture JSON file contains fixtures for all the parametrized test cases for one test function. This means only one error will be reported, even if multiple fixtures fail within one fixture file.

Additionally, it is only executed after all the test cases in the module have been executed[^1] and will only report the first failing test fixture in all files, even if there are multiple failing fixture files.

This means, by default, that the feedback is not as granular as for test case execution. To improve granularity, and get feedback per parametrized test case use `--single-fixture-per-file`.
Additionally, it is only executed after all the test cases in the module have been executed and will only report the first failing test fixture in all files, even if there are multiple failing fixture files. This limitation is required to enable support of the [`pytest-xdist` plugin](https://github.com/pytest-dev/pytest-xdist) for concurrent test execution across multiple CPUs. To achieve this we use the we apply the `--dist loadscope` xdist flag in our `pytest.ini`.

[^1]: <!-- markdownlint-disable MD053 (53=link-image-reference-definitions) -->
This limitation is required to enable support of the [`pytest-xdist` plugin](https://github.com/pytest-dev/pytest-xdist) for concurrent test execution across multiple CPUs. To achieve this we use the we apply the `--dist loadscope` xdist flag in our `pytest-fill.ini`.
This means, by default, that the feedback is not as granular as for test case execution. To improve granularity, and get feedback per parametrized test case use `--single-fixture-per-file`.
{{< /callout >}}
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
# Filling Tests at a Prompt
+++
title = 'Filling Tests at a Prompt'
+++

The execution-spec-tests test framework uses the [pytest framework](https://docs.pytest.org/en/latest/) for test case collection and execution. The `fill` command is essentially an alias for `pytest`, which uses several [custom pytest plugins](../library/pytest_plugins/index.md) to run transition tools against test cases and generate JSON fixtures.
The execution-spec-tests test framework uses the [pytest framework](https://docs.pytest.org/en/latest/) for test case collection and execution. The `fill` command is essentially an alias for `pytest`, which uses several [custom pytest plugins](../library/pytest_plugins/main.md) to run transition tools against test cases and generate JSON fixtures.

!!! note "Options specific to execution-spec-tests"
The command-line options specific to filling tests can be listed via:
{{< callout info "Options specific to execution-spec-tests" >}}
The command-line options specific to filling tests can be listed via:

```console
uv run fill --help
```
```console
uv run fill --help
```

See [Custom `fill` Command-Line Options](#custom-fill-command-line-options) for all options.
See [Custom `fill` Command-Line Options](#custom-fill-command-line-options) for all options.
{{< /callout >}}

## Collection - Test Exploration

Expand Down Expand Up @@ -47,8 +50,9 @@ To generate all the test fixtures defined in the `./tests/shanghai` sub-director
uv run fill ./tests/shanghai --output="fixtures-shanghai"
```

!!! note "Test case verification"
Note, that the (limited set of) test `post` conditions are tested against the output of the `evm t8n` command during test generation.
{{< callout info "Test case verification" >}}
Note, that the (limited set of) test `post` conditions are tested against the output of the `evm t8n` command during test generation.
{{< /callout >}}

To generate all the test fixtures in the `tests/shanghai/eip3651_warm_coinbase/test_warm_coinbase.py` module, for example, run:

Expand Down Expand Up @@ -76,17 +80,18 @@ uv run fill tests/shanghai/eip3651_warm_coinbase/test_warm_coinbase.py::test_war

## Execution for Development Forks

!!! note ""
By default, test cases are not filled for upcoming Ethereum forks so that they can be readily filled using the `evm` tool from the latest `geth` release.
{{< callout info "Note" >}}
By default, test cases are not filled for upcoming Ethereum forks so that they can be readily filled using the `evm` tool from the latest `geth` release.

In order to fill test cases for an upcoming fork, ensure that the `evm` tool used supports that fork and features under test and use the `--until` or `--fork` flag.
In order to fill test cases for an upcoming fork, ensure that the `evm` tool used supports that fork and features under test and use the `--until` or `--fork` flag.

For example, as of Q2 2023, the current fork under active development is `Cancun`:
```console
uv run fill --until Cancun
```
For example, as of Q2 2023, the current fork under active development is `Cancun`:
```console
uv run fill --until Cancun
```
{{< /callout >}}

See: [Filling Tests for Features under Development](./filling_tests_dev_fork.md).
See: [Filling Tests for Features under Development](./filling_tests_dev_fork.md).

## Debugging the `t8n` Command

Expand Down
Loading