documenting_clis.md

Documenting CLIs

EEST command line interfaces (CLIs) are documented using the click library's built-in help system and the 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 and corresponding Python docstrings for the evm_bytes CLI documentation as an example of how to document a CLI using mkdocs-click.