Skip to content

Fix README's command list and trim duplicated detail - #64

Merged
zmofei merged 2 commits into
docs/readme-structurefrom
docs/readme-cleanup
Sep 29, 2026
Merged

zmofei merged 2 commits into
docs/readme-structurefrom
docs/readme-cleanup

Conversation

@zmofei

@zmofei zmofei commented Sep 29, 2026

Copy link
Copy Markdown
Member

Stacked on #63. Merge #62 and #63 first.

Fixes a wrong command list. README's API group list named rasterarrays, static-images, static-tiles and tilequery, none of which the binary has, and left out static. It also never mentioned doctor, usage or config. The list is corrected, and a new Diagnostics and settings section shows those three plus history.

Adds a check so it can't drift again. Two tests in tests/docs_contract.rs:

  • every_command_the_readme_spells_exists: every mapbox … line in a shell block or inline code span must name a real command from mapbox --schema.
  • every_top_level_command_appears_in_the_readme: every top-level command appears at least once.

Run against #63's README, they report exactly the four fake groups and the three missing commands. They also catch a typo in a nested subcommand (styles draft gett). The check is in its own commit, so reverting the README commit shows it failing.

Trims duplicated detail. Agent skills, completion, generate-skills and Tileset CLI are cut to examples plus a link, since docs/commands.md covers each fully. Implementation notes are gone (e.g. why agent-skills has no lock file), and the PowerShell aside is shorter. The installer-test note moves to CONTRIBUTING.md. Update notices, history, logs and Privacy stay as they were: docs/commands.md links to the README for the first three, and Privacy is legal text.

Not checked: the new tests only cover command paths, not flags or descriptions in README prose.

Unrelated but found along the way: REPO_URL in src/main.rs and repository in Cargo.toml point at github.com/mapbox/cli, which redirects to mapbox/cli-opensource-preview, not this repo. It shows up in help text (for example mapbox usage --help). I left it alone in case that's intentional.

The README listed four API groups (rasterarrays, static-images, static-tiles, tilequery) the binary no longer has, and never mentioned doctor, usage or the real static group. Nothing read the README, so nobody noticed.
@zmofei
zmofei requested a review from a team as a code owner September 29, 2026 09:20
@zmofei
zmofei merged commit 4201078 into docs/readme-structure Sep 29, 2026
8 checks passed
@zmofei

zmofei commented Sep 29, 2026

Copy link
Copy Markdown
Member Author

Folded into #63. This shows as merged only because its commits landed on #63's branch; nothing reached main from here.

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