🗒️ Description

WELDs the documentation infrastructure from EEST into the project including automated workflows, tox environments, and tooling to maintain documentation quality.

Key Changes

GitHub Workflows:

• Added .github/workflows/test-docs.yaml workflow to automatically build and validate EEST documentation on push and pull request events
  • Workflow triggers on changes to packages/tests/**, tests/**, and the workflow file itself

Tox Environments:

• changelog: Validates changelog entries
• mkdocs: Builds HTML documentation using mkdocs with strict mode enabled
• markdownlint: Lints markdown files using markdownlint
• spec-docs: Generate documentation for the specification code using docc

Documentation Tooling:

• Added src/ethereum_spec_tools/whitelist.py: Python script to manage the codespell whitelist with proper alphabetical sorting and formatting
• Added EESTs .markdownlint.yaml: Configuration for markdownlint with appropriate rule customizations
• Updated whitelist.txt: Consolidated EEST's whitelist into ours, cleaned up codespell whitelist entries
• Added docs/templates/function_parameter_datatable.html.j2: Jinja2 template for rendering function parameter documentation

Configuration Updates:

• Updated tox.ini with new documentation environments and proper dependencies
• Added mkdocs-related dependencies (mkdocstrings[python], etc.) to documentation extras
• Configured proper path triggers for CI workflows

Benefits

1. Automated Quality Checks: Documentation is automatically validated on every PR
2. Consistent Formatting: Standardized markdown linting and spell checking
3. Developer Experience: Easy-to-use tox commands for local documentation building and validation
4. Maintainability: Centralized whitelist management tool prevents ad-hoc additions

Usage

# Build EEST documentation
uv run tox -e eest-mkdocs

# Run all EEST doc checks
uv run tox -e eest-docs

# Run all documentation checks (EEST + main specs)
uv run tox -e docs

# Add words to codespell whitelist
uv run whitelist word1 word2...

🔗 Related Issues or PRs

Part of the WELD milestone (❄️ WELD Freeze ❄️)

✅ Checklist

• All: Ran fast tox checks to avoid unnecessary CI fails, see also Code Standards and Enabling Pre-commit Checks:

  uvx --with=tox-uv tox -e static

• All: PR title adheres to the repo standard - it will be used as the squash commit message and should start type(scope):.
• All: Considered adding an entry to CHANGELOG.md.
• All: Considered updating the online docs in the ./docs/ directory.
• All: Set appropriate labels for the changes (only maintainers can apply labels).
• Tests: Ran mkdocs serve locally and verified the auto-generated docs for new tests in the Test Case Reference are correctly formatted.
• [N/A ] Tests: For PRs implementing a missed test case, update the post-mortem document to add an entry the list.
• [N/A ] Ported Tests: All converted JSON/YML tests from ethereum/tests or tests/static have been assigned @ported_from marker.
• Find-replace mkdocstrings prefixes: ::: with the new package paths
• Finish updating new whitelist tool to be installable and directly invokable (e.g. whitelist word1 word2)

Cute Animal Picture

Credit to Linnaea Mallette:

• 🕸️ website
• 📖 Facebook
• 🪙 Tip the Artist!
  License: CC0 Public Domain