Skip to content

docs: generate a matrix of commands and options in each build - #35

Merged
NaNIsaac merged 1 commit into
mainfrom
docs/cli-matrix
Oct 23, 2026
Merged

NaNIsaac merged 1 commit into
mainfrom
docs/cli-matrix

Conversation

@NaNIsaac

Copy link
Copy Markdown
Owner

Tier: medium (docs plus a new Rust example target; no src change)

  • Adds docs/cli-matrix.md and docs/cli-matrix.json: every command and option of the Python and Rust builds on main, classified as both / python-only / rust-only / hidden / pending, plus a hand-kept behavior table.
  • Adds docs/cli_matrix.py (generator, --check mode) and rust/examples/cli_options.rs, which dumps the clap command tree (hidden options included) as JSON.
  • Nothing under site/ changes; the JSON is meant for the site lane's reference check.

Sources. The Python build is read from Typer the way site/scripts/check_reference.py reads it; the Rust build from clap itself (Cli::command()), not from --help text, because --help hides --no-copy and term ingest.

JSON for the reference check. "python" and "rust" map each command path to its sorted option names, the shape check_reference.cli_options() returns. Checked locally: "python" equals cli_options() exactly (sets compared as sorted lists), and the Rust build has the same command paths, with one extra option, term --raw.

What the matrix shows on main (c1c4d11): 21 commands in both builds (term ingest hidden in both); 64 options in both, 1 Rust only (term --raw), 0 Python only. Differences in names: --version also takes -V in Rust; --no-copy is hidden from Rust's --help but listed by Python's. Pending (not on main): the remote scan options of scan (Python in #33, Rust waits for the decision in DotFiles#81) and mcp --allow-remote (planned in #30). Nothing in either build is marked experimental, so that category is empty and says so.

Behavior table. Differences that are not options (digest languages, outlines of broken Python, pack module order, Ctrl+C in cap, status line endings, remote scan) are copied by hand from rust/README.md "Differences from the Python build"; the generator says so and does not check them.

Tests: uv run python docs/cli_matrix.py --check passes after generation; cargo clippy --example cli_options -- -D warnings and cargo fmt --check clean; ruff@0.17.1 check/format --check clean; conventions.py check 0 findings. Not added: a CI step that runs --check (it needs cargo in the Python job, or the Rust job to run the Python script); proposed for a follow-up.

@NaNIsaac
NaNIsaac merged commit 6eb1d37 into main Oct 23, 2026
9 checks passed
@NaNIsaac
NaNIsaac deleted the docs/cli-matrix branch October 23, 2026 15:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant