From d1f8ae15b81702f9693bd9193c67fda747ae0a29 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 26 Sep 2024 17:49:40 +0200 Subject: [PATCH] fix(docs): miscellaneous improvements to troubleshooting, navigation, styling (#840) * feat(docs): add solc certificate installation issue to troubleshooting * fix(docs): update to new discord channel, el-testing * fix(docs): fix unrecognized code block language spec * fix(docs): add test_actions_locally.md to nav menu * fix(docs): fix existing pytest plugins nav (needs more work) * feat(docs): include gen_test_doc plugin doc in docs.md * feat(docs): describe how to work with EEST packages interactively * fix(docs): update whitelist; fix tox --- docs/dev/docs.md | 6 + docs/dev/interactive_usage.md | 36 ++++++ docs/dev/test_actions_locally.md | 6 +- docs/getting_help/index.md | 2 +- .../installation_troubleshooting.md | 105 ++++++++++++------ docs/library/pytest_plugins/index.md | 4 + docs/library/pytest_plugins/navigation.md | 5 - docs/navigation.md | 3 +- whitelist.txt | 3 + 9 files changed, 127 insertions(+), 43 deletions(-) create mode 100644 docs/dev/interactive_usage.md delete mode 100644 docs/library/pytest_plugins/navigation.md diff --git a/docs/dev/docs.md b/docs/dev/docs.md index 0e4cb33d06..cfce9251bf 100644 --- a/docs/dev/docs.md +++ b/docs/dev/docs.md @@ -31,6 +31,12 @@ This runs continually: Deploys the site locally and re-generates the site upon m uv run mkdocs serve ``` +For more help (including ensuring a clean build), see the `gen_test_doc` pytest plugin's documentation: + +::: src.pytest_plugins.filler.gen_test_doc.gen_test_doc + options: + members: no + ## Remote Deployment and Versioning The execution-specs-test docs are hosted on Github pages at the [repo's Github pages](https://ethereum.github.io/execution-spec-tests/). Versions are updated/deployed automatically as part of Github Actions, but this can also be performed on the command-line. diff --git a/docs/dev/interactive_usage.md b/docs/dev/interactive_usage.md new file mode 100644 index 0000000000..fab788ed0f --- /dev/null +++ b/docs/dev/interactive_usage.md @@ -0,0 +1,36 @@ +# Working with EEST Libraries Interactively + +You can work with EEST Python packages interactively with `ipython` using: + +```console +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`" + + 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} + ``` + +## Required `ipython` Configuration + +To enable [autoreload](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html) of changed modules in the current `ipython` session, type: + +```python +%load_ext autoreload +%autoreload 2 +``` + +To make this configuration persistent, add/uncomment the following lines to `~/.ipython/profile_default/ipython_config.py`: + +```python +c.InteractiveShellApp.exec_lines = ["%autoreload 2"] +c.InteractiveShellApp.extensions = ["autoreload"] +``` diff --git a/docs/dev/test_actions_locally.md b/docs/dev/test_actions_locally.md index 0c47296e08..1ddfd5f6b0 100644 --- a/docs/dev/test_actions_locally.md +++ b/docs/dev/test_actions_locally.md @@ -8,7 +8,7 @@ The Github Actions workflows can be tested locally using [nektos/act](https://gi 2. Install the Github CLI (`gh`) for authentication: [linux](https://github.com/cli/cli/blob/trunk/docs/install_linux.md), [macos](https://github.com/cli/cli/tree/trunk?tab=readme-ov-file#macos). 3. Authenticate with the Github CLI: - ```shell + ```bash gh auth login ``` @@ -17,8 +17,8 @@ The Github Actions workflows can be tested locally using [nektos/act](https://gi ### Testing a Workflow that uses a Matrix Strategy ```bash - act -j build --workflows .github/workflows/tox_verify.yaml -s GITHUB_TOKEN=$(gh auth token) --matrix python:3.10 - ``` +act -j build --workflows .github/workflows/tox_verify.yaml -s GITHUB_TOKEN=$(gh auth token) --matrix python:3.10 +``` ### Testing Release Builds diff --git a/docs/getting_help/index.md b/docs/getting_help/index.md index c681b564d2..8e370fb6b4 100644 --- a/docs/getting_help/index.md +++ b/docs/getting_help/index.md @@ -2,7 +2,7 @@ The tests in this repository are a community effort to help improve the development cycle of all Ethereum execution clients. -We encourage contributions and recognize that Python is not everyone's primary language - if you stumble over issues or need help, please reach out to one of the execution-spec-tests maintainers either directly or in the `#testing` channel in the [Ethereum R&D Discord Server](https://discord.com/invite/qGpsxSA). +We encourage contributions and recognize that Python is not everyone's primary language - if you stumble over issues or need help, please reach out to one of the execution-spec-tests maintainers either directly or in the `#el-testing` channel in the [Ethereum R&D Discord Server](https://discord.com/invite/qGpsxSA). ## Contact the Maintainers diff --git a/docs/getting_started/installation_troubleshooting.md b/docs/getting_started/installation_troubleshooting.md index e8a9a30ee0..408029764d 100644 --- a/docs/getting_started/installation_troubleshooting.md +++ b/docs/getting_started/installation_troubleshooting.md @@ -1,35 +1,74 @@ # Installation Troubleshooting -This page provides guidance on how to troubleshoot common issues that may arise when installing the Execution Spec Tests repository. - -## `uv`/`pip` Installation Issues - -### Coincurve Installation - -If you encounter an error when installing the `coincurve` package like the following: - -```bash -Stored in directory: /tmp/... - Building wheel for coincurve (pyproject.toml) ... error - error: subprocess-exited-with-error - - × Building wheel for coincurve (pyproject.toml) did not run successfully. - │ exit code: 1 - ╰─> [27 lines of output] - ... - 571 | #include - | ^~~~~~~~~~~~~~~~~~~~~~~ - compilation terminated. - error: command '/usr/bin/gcc' failed with exit code 1 - [end of output] - - note: This error originates from a subprocess, and is likely not a problem with pip. - ERROR: Failed building wheel for coincurve -``` - -You may need to install the `libsecp256k1` library. On Ubuntu, you can install this library by running the following command: - -```bash -sudo apt update -sudo apt-get install libsecp256k1-dev -``` +This page provides guidance on how to troubleshoot common issues that may arise when installing [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests). + +## Problem: `Failed building wheel for coincurve` + +!!! danger "Problem: `Failed building wheel for coincurve`" + Installing EEST and its dependencies via `uv sync --all-extras` fails with: + + ```bash + Stored in directory: /tmp/... + Building wheel for coincurve (pyproject.toml) ... error + error: subprocess-exited-with-error + + × Building wheel for coincurve (pyproject.toml) did not run successfully. + │ exit code: 1 + ╰─> [27 lines of output] + ... + 571 | #include + | ^~~~~~~~~~~~~~~~~~~~~~~ + compilation terminated. + error: command '/usr/bin/gcc' failed with exit code 1 + [end of output] + + note: This error originates from a subprocess, and is likely not a problem with pip. + ERROR: Failed building wheel for coincurve + ``` + +!!! success "Solution: Install the `libsecp256k1` library" + On Ubuntu, you can install this library with: + + ```bash + sudo apt update + sudo apt-get install libsecp256k1-dev + ``` + +## Problem: `solc` Installation issues + +!!! danger "Problem: `Failed to install solc ... CERTIFICATE_VERIFY_FAILED`" + When running either `uv run solc-select use 0.8.24 --always-install` or `fill` you encounter the following error: + + ```bash + Exit: Failed to install solc version 0.8.24: + ``` + +=== "Ubuntu" + + !!! success "Solution: Update your system’s CA certificates" + On Ubuntu, run the following commands: + + ```bash + sudo apt-get update + sudo apt-get install ca-certificates + ``` + +=== "macOS" + + !!! success "Solution: Update your system’s CA certificates" + On macOS, Python provides a built-in script to install the required certificates: + + ```bash + /Applications/Python\ 3.11/Install\ Certificates.command + ``` + +## Other Issues Not Listed? + +If you're facing an issue that's not listed here, you can easily report it on GitHub for resolution. + +[Click here to report a documentation issue related to installation](https://github.com/ethereum/execution-spec-tests/issues/new?title=docs(bug):%20unable%20to%20install%20eest%20with%20error%20...&labels=scope:docs,type:bug&body=%3Ccopy-paste%20command%20that%20triggered%20the%20issue%20here%3E%0A%3Ccopy-paste%20output%20or%20attach%20screenshot%20here%3E) + +Please include the following details in your report: + +1. The command that triggered the issue. +2. Any relevant error messages or screenshots. diff --git a/docs/library/pytest_plugins/index.md b/docs/library/pytest_plugins/index.md index c91fad2728..e083fad56d 100644 --- a/docs/library/pytest_plugins/index.md +++ b/docs/library/pytest_plugins/index.md @@ -1,3 +1,7 @@ # Pytest Framework and Customizations ::: pytest_plugins + +- [Filler Plugin](./filler.md). +- [Forks Plugin](./forks.md). +- [Spec Version Checker Plugin](./spec_version_checker.md). diff --git a/docs/library/pytest_plugins/navigation.md b/docs/library/pytest_plugins/navigation.md deleted file mode 100644 index 995ff2ed10..0000000000 --- a/docs/library/pytest_plugins/navigation.md +++ /dev/null @@ -1,5 +0,0 @@ - -* [Overview](index.md) -* [Forks](forks.md) -* [Test Filler](filler.md) -* [Spec Version Checker](spec_version_checker.md) diff --git a/docs/navigation.md b/docs/navigation.md index 14ff9393e6..2dabf851b6 100644 --- a/docs/navigation.md +++ b/docs/navigation.md @@ -29,9 +29,11 @@ * [Exceptions](consuming_tests/exceptions.md) * [Getting Help](getting_help/index.md) * [Developer Doc](dev/index.md) + * [Interactive Library Usage](dev/interactive_usage.md) * [Documentation](dev/docs.md) * [Coding Style](dev/coding_style.md) * [Enabling Precommit Checks](dev/precommit.md) + * [Running Github Actions Locally](dev/test_actions_locally.md) * [Changelog](CHANGELOG.md) * [Library Reference](library/index.md) * [Ethereum Test Base Types Package](library/ethereum_test_base_types.md) @@ -44,4 +46,3 @@ * [Ethereum Test VM Package](library/ethereum_test_vm.md) * [EVM Transition Tool Package](library/evm_transition_tool.md) * [Pytest Plugins](library/pytest_plugins/index.md) - * [Filler Plugin](library/pytest_plugins/filler.md) diff --git a/whitelist.txt b/whitelist.txt index bff2bda85d..68cc1dd56a 100644 --- a/whitelist.txt +++ b/whitelist.txt @@ -134,6 +134,8 @@ EOF1 EOFException eofparse esbenp +EEST +EEST's eth ethash ethereum @@ -222,6 +224,7 @@ initcode inputdata instantiation io +ipython isidentifier islice isort