feat(docs): use mkdocs-click for documenting CLIs (#985)

docs/dev/documenting_clis.md

@@ -0,0 +1,10 @@
+# Documenting CLIs
+
+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.
+
+Current limitations:
+
+1. `mkdocs serve` does not automatically update the CLI documentation when the source code changes. You must restart the server to see the changes.
+2. `mkdocs-click` does not automatically generate a short help string from sub-command docstrings. You must provide a short help string for each sub-command in the source code with `@click.command(short_help="...")`.
+
+See the [markdown](https://github.com/ethereum/execution-spec-tests/blob/main/docs/library/cli/evm_bytes.md) and corresponding [Python docstrings](https://github.com/ethereum/execution-spec-tests/blob/main/src/cli/evm_bytes.py) for the [`evm_bytes` CLI documentation](../library/cli/evm_bytes.md) as an example of how to document a CLI using `mkdocs-click`.

docs/dev/index.md

@@ -5,6 +5,7 @@ This documentation is aimed at maintainers of `execution-spec-tests` but may be
 - [Managing configurations](./configurations.md): Instructions for setting up and modifying test configurations.
 - [Interactive usage](./interactive_usage.md): Guide on interactive use of EEST packages using `ipython`.
 - [Generating documentation](./docs.md): Steps to create and build documentation for the project.
+- [Documenting CLI commands](./documenting_clis.md): Instructions for documenting command line interfaces (CLIs).
 - [Coding style](./coding_style.md): Standards and best practices for code formatting and to maintain consistency across the repository.
 - [Enabling pre-commit checks](./precommit.md): A guide for setting up pre-commit hooks to enforce code quality before commits.
 - [Running github actions locally](./test_actions_locally.md): Instructions for testing GitHub Actions workflows on your local machine to streamline development and debugging.

docs/library/cli/evm_bytes.md

@@ -1,20 +1,7 @@
 # The `evm_bytes` CLI
 
-::: cli.evm_bytes.cli
-    options:
-        show_source: false
-        show_root_toc_entry: false
-
-## `evm_bytes hex-string <bytecode>`
-
-::: cli.evm_bytes.hex_string
-    options:
-        show_source: false
-        show_root_toc_entry: false
-
-## `evm_bytes binary-file <contract.bin>`
-
-::: cli.evm_bytes.binary_file
-    options:
-        show_source: false
-        show_root_toc_entry: false
+::: mkdocs-click
+    :module: cli.evm_bytes
+    :command: evm_bytes
+    :depth: 1
+    :list_subcommands: true

docs/navigation.md

@@ -35,6 +35,7 @@
     * [Managing Configurations](dev/configurations.md)
     * [Interactive Library Usage](dev/interactive_usage.md)
     * [Generating Documentation](dev/docs.md)
+    * [Documenting CLI Commands](dev/documenting_clis.md)
     * [Coding Style](dev/coding_style.md)
     * [Enabling Precommit Checks](dev/precommit.md)
     * [Running Github Actions Locally](dev/test_actions_locally.md)

mkdocs.yml

@@ -71,6 +71,7 @@ markdown_extensions:
   - def_list
   - footnotes
   - md_in_html
+  - mkdocs-click
   - toc:
       permalink: true
       toc_depth: 4

pyproject.toml

@@ -77,6 +77,7 @@ docs = [
     "cairosvg>=2.7.0,<3",
     "mike>=1.1.2,<2",
     "mkdocs>=1.4.3,<2",
+    "mkdocs-click>=0.8,<1",
     "mkdocs-gen-files>=0.5.0,<1",
     "mkdocs-git-authors-plugin>=0.7.1,<1",
     "mkdocs-glightbox>=0.3.4,<1",
@@ -104,7 +105,7 @@ eofwrap = "cli.eofwrap:eof_wrap"
 pyspelling_soft_fail = "cli.tox_helpers:pyspelling"
 markdownlintcli2_soft_fail = "cli.tox_helpers:markdownlint"
 order_fixtures = "cli.order_fixtures:order_fixtures"
-evm_bytes = "cli.evm_bytes:cli"
+evm_bytes = "cli.evm_bytes:evm_bytes"
 hasher = "cli.hasher:main"
 env_init = "config.env:create_default_config"
 et = "cli.et.cli:et"

src/cli/evm_bytes.py

@@ -148,94 +148,87 @@ def process_evm_bytes_string(evm_bytes_hex_string: str, assembly: bool = False)
     "--assembly",
     default=False,
     is_flag=True,
-    help="Output the code as assembly instead of python.",
+    help="Output the code as assembly instead of Python Opcodes.",
 )
 
 
-@click.group(context_settings=dict(help_option_names=["-h", "--help"]))
-def cli():
+@click.group("evm_bytes", context_settings=dict(help_option_names=["-h", "--help"]))
+def evm_bytes():
     """
-    Convert the given EVM bytes to EEST's python opcodes or assembly string.
+    Convert EVM bytecode to EEST's Python Opcodes or an assembly string.
 
     The input can be either a hex string or a binary file containing EVM bytes.
     """
     pass
 
 
-@cli.command()
+@evm_bytes.command(short_help="Convert a hex string to Python Opcodes or assembly.")
 @assembly_option
 @click.argument("hex_string")
 def hex_string(hex_string: str, assembly: bool):
     """
-    Process a hex string representing EVM bytes and convert it into EEST's Python opcodes.
+    Convert the HEX_STRING representing EVM bytes to EEST Python Opcodes.
 
-    Args:
-        hex_string (str): The hex string representing the EVM bytes.
-        assembly (bool): Whether to print the output as assembly or Python opcodes.
+    HEX_STRING is a string containing EVM bytecode.
 
     Returns:
+
         (str): The processed EVM opcodes in Python or assembly format.
 
-    Example: Convert a hex string to EEST Python `Opcodes`
-        ```bash
+    Example 1: Convert a hex string to EEST Python `Opcodes`
+
         uv run evm_bytes hex-string 604260005260206000F3
-        ```
 
-        Output:
+    Output 1:
 
-        ```python
+        \b
         Op.PUSH1[0x42] + Op.PUSH1[0x0] + Op.MSTORE + Op.PUSH1[0x20] + Op.PUSH1[0x0] + Op.RETURN
-        ```
 
-    Example: Convert a hex string to assembly
-        ```bash
+    Example 2: Convert a hex string to assembly
+
         uv run evm_bytes hex-string --assembly 604260005260206000F3
-        ```
 
-        Output:
+    Output 2:
 
-        ```text
+        \b
         push1 0x42
         push1 0x00
         mstore
         push1 0x20
         push1 0x00
         return
-        ```
-    """  # noqa: E501
+    """  # noqa: D301
     processed_output = process_evm_bytes_string(hex_string, assembly=assembly)
     click.echo(processed_output)
 
 
-@cli.command()
+@evm_bytes.command(short_help="Convert a binary file to Python Opcodes or assembly.")
 @assembly_option
-@click.argument("binary_file_path", type=click.File("rb"))
-def binary_file(binary_file_path, assembly: bool):
+@click.argument("binary_file", type=click.File("rb"))
+def binary_file(binary_file, assembly: bool):
     """
-    Convert the given EVM bytes binary file.
+    Convert the BINARY_FILE containing EVM bytes to Python Opcodes or assembly.
+
+    BINARY_FILE is a binary file containing EVM bytes, use `-` to read from stdin.
 
-    Args:
-        binary_file_path (BinaryIO): A binary file containing EVM bytes to be processed or use `-`
-            to read from stdin.
-        assembly (bool): Whether to print the output as assembly or Python opcodes.
+    Returns:
+
+        (str): The processed EVM opcodes in Python or assembly format.
 
     Example: Convert the Withdrawal Request contract to assembly
-        ```bash
+
+        \b
         uv run evm_bytes binary-file ./src/ethereum_test_forks/forks/contracts/withdrawal_request.bin --assembly
-        ```
 
-        Output:
+    Output:
 
-        ```text
+        \b
         caller
         push20 0xfffffffffffffffffffffffffffffffffffffffe
         eq
         push1 0x90
         jumpi
         ...
-        ```
-    """  # noqa: E501
-    processed_output = format_opcodes(
-        process_evm_bytes(binary_file_path.read()), assembly=assembly
-    )
+    """  # noqa: E501,D301
+    processed_output = format_opcodes(process_evm_bytes(binary_file.read()), assembly=assembly)
     click.echo(processed_output)

whitelist.txt

@@ -400,6 +400,7 @@ str
 streetsidesoftware
 subcall
 subclasscheck
+subcommands
 subdir
 subdirectories
 subdirectory