fix(docs): Add workflows and tox envs for building docs

.github/workflows/fixture_feature_release.yaml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
           submodules: false
-      
+
       - name: Get feature names
         id: feature-name
         shell: bash
@@ -25,7 +25,7 @@ jobs:
           names=$(grep -Po "^${FEATURE_NAME}(?=:)" .github/configs/feature.yaml | jq  --raw-input .  | jq -c --slurp .)
           echo names=${names}
           echo names=${names} >> "$GITHUB_OUTPUT"
-  
+
   build:
     needs: feature-names
     runs-on: [self-hosted-ghr, size-gigachungus-x64]
@@ -37,7 +37,7 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
           submodules: true
-      
+
       - name: Fetch lllc
         uses: ./.github/actions/fetch-binary
         with:
@@ -47,7 +47,7 @@ jobs:
           remote_name: lllc
           binary_name: lllc
           expected_sha256: 865a0d5379acb3b5471337b5dcf686a2dd71587c6b65b9da6c963de627e0b300
-      
+
       - name: Fetch Solidity
         uses: ./.github/actions/fetch-binary
         with:
@@ -57,13 +57,13 @@ jobs:
           remote_name: solc-static-linux
           binary_name: solc
           expected_sha256: fb03a29a517452b9f12bcf459ef37d0a543765bb3bbc911e70a87d6a37c30d5f
-      
+
       - uses: ./.github/actions/build-fixtures
         with:
           release_name: ${{ matrix.feature }}
           uv_version: ${{ vars.UV_VERSION }}
           python_version: ${{ vars.DEFAULT_PYTHON_VERSION }}
-  
+
   release:
     runs-on: ubuntu-latest
     needs: build
@@ -78,7 +78,7 @@ jobs:
           gh run download ${{ github.run_id }} --dir ./artifacts
         env:
           GH_TOKEN: ${{ github.token }}
-        
+
       - name: Draft Pre-release to EEST Repository
         run: |
           # Strip "tests-" prefix from tag for EEST
@@ -92,4 +92,4 @@ jobs:
             --generate-notes \
             ./artifacts/**/*
         env:
-          GH_TOKEN: ${{ secrets.EEST_RELEASE_TOKEN }}
+          GH_TOKEN: ${{ secrets.EEST_RELEASE_TOKEN }}

.github/workflows/fixture_full_release.yaml

@@ -1,4 +1,4 @@
-name: Create Fixture Full Release 
+name: Create Fixture Full Release
 
 on:
   push:
@@ -77,17 +77,17 @@ jobs:
           gh run download ${{ github.run_id }} --dir ./artifacts
         env:
           GH_TOKEN: ${{ github.token }}
-          
+
       - name: Create Release
         run: |
           # Strip "tests-" prefix from tag for EEST
           TAG_NAME="${{ github.ref_name }}"
           RELEASE_TAG="${TAG_NAME#tests-}"
-            
+
           gh release create "$RELEASE_TAG" \
             --repo ethereum/execution-spec-tests \
             --draft \
             --generate-notes \
             ./artifacts/**/*
         env:
-          GH_TOKEN: ${{ secrets.EEST_RELEASE_TOKEN }}
+          GH_TOKEN: ${{ secrets.EEST_RELEASE_TOKEN }}

.github/workflows/gh-pages.yaml

@@ -3,7 +3,6 @@ name: render
 on:
   push:
     branches:
-      - master
       - mainnet
       - 'forks/**'
     paths: &render_paths
@@ -42,7 +41,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          tox -e doc
+          tox -e spec-docs
           touch .tox/docs/.nojekyll
 
       - name: Upload Pages Artifact

.github/workflows/test-docs.yaml

@@ -0,0 +1,52 @@
+name: Spec Docs
+
+on:
+  push:
+    branches:
+      - mainnet
+      - 'forks/**'
+    paths:
+      - 'packages/testing/**'
+      - 'tests/**'
+      - '.github/workflows/test-docs.yaml'
+      - 'docs/**'
+  pull_request:
+    paths:
+      - 'packages/testing/**'
+      - 'tests/**'
+      - '.github/workflows/test-docs.yaml'
+      - 'docs/**'
+  workflow_dispatch:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+    cancel-in-progress: true
+
+jobs:
+  changelog:
+    name: Validate changelog entries
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout ethereum/execution-specs
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - name: Install uv ${{ vars.UV_VERSION }} and python ${{ vars.DEFAULT_PYTHON_VERSION }}
+        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          version: ${{ vars.UV_VERSION }}
+          python-version: ${{ vars.DEFAULT_PYTHON_VERSION }}
+      - name: Run changelog validation via tox
+        run: uvx --with=tox-uv tox -e changelog
+
+  markdownlint:
+      name: Lint markdown files with markdownlint
+      runs-on: ubuntu-latest
+      steps:
+          - name: Checkout ethereum/execution-specs
+            uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+          - uses: DavidAnson/markdownlint-cli2-action@05f32210e84442804257b2a6f20b273450ec8265
+            with:
+                globs: |
+                    docs/**/*.md |
+                    *.md

.gitignore

@@ -63,7 +63,6 @@ pip-delete-this-directory.txt
 .tox/
 
 /doc/_autosummary
-/docs
 
 .coverage
 .coverage.*
@@ -80,5 +79,6 @@ fixtures/
 logs/
 *.log
 
-# config (output of `uv run make env`)
-env.yaml
+env.yaml
+
+site/

.markdownlint.yaml

@@ -0,0 +1,10 @@
+# All rules: https://github.com/DavidAnson/markdownlint#rules--aliases
+default: true # Default state for all rules
+MD013: false # line-length: We don't fill paragraphs/limit line length
+MD034: false # no-bare-urls - We use pymdownx.magiclink which allows bare urls
+MD046: false # code-block-style - This doesn't play well with material's admonitions)
+MD024: false # no-duplicate-heading - We use duplicate headings in the changelog.
+MD033: false # no-inline-html - Too strict.
+ul-indent:
+  indent: 4
+  start_indent: 4

CONTRIBUTING.md

@@ -13,7 +13,6 @@ In particular, we appreciate support in the following areas:
 
 For details about EELS usage and building, please refer the [README](https://github.com/ethereum/execution-specs/blob/master/README.md#usage)
 
-
 ## Contribution Guidelines
 
 This specification aims to be:
@@ -26,7 +25,7 @@ This specification aims to be:
 
 - Attempt to use descriptive English words (or _very common_ abbreviations) in documentation and identifiers.
 - Avoid using EIP numbers in identifiers.
-- If necessary, there is a custom dictionary `whitelist.txt`. 
+- If necessary, there is a custom dictionary `whitelist.txt`.
 
 ### Changes across various Forks
 
@@ -43,39 +42,39 @@ This saves you having to apply code review feedback repeatedly for each fork.
 
 Running the tests necessary to merge into the repository requires:
 
- * Python 3.11.x, and
- * [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later.
- * `geth` installed and present in `$PATH`
-
+- Python 3.11.x, and
+- [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later.
+- `geth` installed and present in `$PATH`
 
 `execution-specs` depends on a submodule that contains common tests that are run across all clients, so we need to clone the repo with the --recursive flag. Example:
+
 ```bash
-$ git clone --recursive https://github.com/ethereum/execution-specs.git
+git clone --recursive https://github.com/ethereum/execution-specs.git
 ```
 
 Or, if you've already cloned the repository, you can fetch the submodules with:
 
 ```bash
-$ git submodule update --init --recursive
+git submodule update --init --recursive
 ```
 
 The tests can be run with:
+
 ```bash
-$ tox
+tox
 ```
 
 The development tools can also be run outside of `tox`, and can automatically reformat the code:
 
 ```bash
-$ uv run --extra lint ruff check                # Detects code issues and produces a report to STDOUT
-$ uv run --extra lint ruff check --fix          # Fixes minor code issues (like unsorted imports).
-$ uv run --extra lint ruff format               # Formats code.
-$ uv run --extra lint mypy src packages tests   # Verifies type annotations.
+uv run --extra lint ruff check                # Detects code issues and produces a report to STDOUT
+uv run --extra lint ruff check --fix          # Fixes minor code issues (like unsorted imports).
+uv run --extra lint ruff format               # Formats code.
+uv run --extra lint mypy src packages tests   # Verifies type annotations.
 ```
 
 It is recommended to use a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to keep your system Python installation clean.
 
-
 A trace of the EVM execution for any test case can be obtained by providing the `--evm-trace` argument to pytest.
 Note: Make sure to run the EVM trace on a small number of tests at a time. The log might otherwise get very big.
 Below is an example.
@@ -86,20 +85,20 @@ uv run --extra test \
         --evm_trace
 ```
 
-
 ## CLI Utilities `ethereum_spec_tools`
 
 The EELS repository has various CLI utilities that can help in the development process.
 
 ### New Fork Tool
------------------
+
 This tool can be used to create the base code for a new fork by using the existing code from a given fork.
 
 The command takes 4 arguments, 2 of which are optional
- * from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle"
- * to_fork: The fork name of the new fork Eg - "Spurious Dragon"
- * from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150"
- * to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158"
+
+- from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle"
+- to_fork: The fork name of the new fork Eg - "Spurious Dragon"
+- from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150"
+- to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158"
 
 As an example, if one wants to create baseline code for the `Spurious Dragon` fork from the `Tangerine Whistle` one
 
@@ -108,46 +107,45 @@ ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spurious Drago
 ```
 
 The following will have to however, be updated manually
- 1. The fork number and `MAINNET_FORK_BLOCK` in `__init__.py`. If you are proposing a new EIP, please set `MAINNET_FORK_BLOCK` to `None`.
- 2. Any absolute package imports from other forks eg. in `trie.py`
- 3. Package names under `setup.cfg`
- 4. Add the new fork to the `monkey_patch()` function in `src/ethereum_optimized/__init__.py`
- 5. Adjust the underline in `fork/__init__.py`
 
+1. The fork number and `MAINNET_FORK_BLOCK` in `__init__.py`. If you are proposing a new EIP, please set `MAINNET_FORK_BLOCK` to `None`.
+2. Any absolute package imports from other forks eg. in `trie.py`
+3. Package names under `setup.cfg`
+4. Add the new fork to the `monkey_patch()` function in `src/ethereum_optimized/__init__.py`
+5. Adjust the underline in `fork/__init__.py`
 
 ### Sync Tool
--------------
+
 The sync tool allows one to use an RPC provider to fetch and validate blocks against EELS.
 The state can also be stored in a local DB after validation. Since syncing directly with the specs can be
 very slow, one can also leverage the optimized module. This contains alternative implementations of routines
 in EELS that have been optimized for speed rather than clarity/readability.
 
-
 The tool can be called using the `ethereum-spec-sync` command which takes the following arguments
- * rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/`
- * unoptimized: Don't use the optimized state/ethash (this can be extremely slow)
- * persist: Store the state in a db in this file
- * geth: Use geth specific RPC endpoints while fetching blocks
- * reset: Delete the db and start from scratch
- * gas-per-commit: Commit to db each time this much gas is consumed. Defaults to 1_000_000_000
- * initial-state: Start from the state in this db, rather than genesis
- * stop-at: After syncing this block, exit successfully
+
+- rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/`
+- unoptimized: Don't use the optimized state/ethash (this can be extremely slow)
+- persist: Store the state in a db in this file
+- geth: Use geth specific RPC endpoints while fetching blocks
+- reset: Delete the db and start from scratch
+- gas-per-commit: Commit to db each time this much gas is consumed. Defaults to 1_000_000_000
+- initial-state: Start from the state in this db, rather than genesis
+- stop-at: After syncing this block, exit successfully
 
 - The following options are not supported WITH `--unoptimized` -> `--persist`, `--initial-state`, `--reset`
 - The following options are not supported WITHOUT `--persist` -> `--initial_state`, `--reset`
 
-
 ### Patch Tool
---------------
+
 This tool can be used to apply the unstaged changes in `SOURCE_FORK` to each of the `TARGET_FORKS`. If some
 of the change didn't apply, '.rej' files listing the unapplied changes will be left in the `TARGET_FORK`.
 
-
 The tool takes the following command line arguments
- * The fork name where the changes have been made. Eg:- `frontier` (only a single fork name)
- * The fork names where the changes have to be applied. Eg:- `homestead` (multiple values can be provided separated by space)
- * optimized: Patch the optimized code instead
- * tests: Patch the tests instead
+
+- The fork name where the changes have been made. Eg:- `frontier` (only a single fork name)
+- The fork names where the changes have to be applied. Eg:- `homestead` (multiple values can be provided separated by space)
+- optimized: Patch the optimized code instead
+- tests: Patch the tests instead
 
 As an example, if one wants to apply changes made in `Frontier` fork to `Homestead` and `Tangerine Whistle`
 
@@ -156,11 +154,12 @@ python src/ethereum_spec_tools/patch_tool.py frontier homestead tangerine_whistl
 ```
 
 ### Lint Tool
--------------
+
 This tool checks for style and formatting issues specific to EELS and emits diagnostics
 when issues are found
 
 The tool currently performs the following checks
+
 - The order of the identifiers between each hardfork is consistent.
 - Import statements follow the relevant import rules in modules.