fix(docs): miscellaneous improvements to troubleshooting, navigation,…

… styling (ethereum#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
spencer-tb · Sep 26, 2024 · d1f8ae1 · d1f8ae1
1 parent 22c734a
commit d1f8ae1
Show file tree

Hide file tree

Showing 9 changed files with 127 additions and 43 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 <secp256k1_extrakeys.h>
-            |          ^~~~~~~~~~~~~~~~~~~~~~~
-      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 <secp256k1_extrakeys.h>
+                |          ^~~~~~~~~~~~~~~~~~~~~~~
+          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: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:992)>
+    ```
+
+=== "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
@@ -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
diff --git 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
@@ -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