Skip to content

fix(docs): omit hidden commands from markdown - #1315

Merged
jdx merged 1 commit into
mainfrom
fix/markdown-hidden-commands
Aug 25, 2026
Merged

jdx merged 1 commit into
mainfrom
fix/markdown-hidden-commands

Conversation

@jdx

@jdx jdx commented Aug 25, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • filter hidden commands from single-file Markdown references
  • add regression coverage for hidden command headings and help text

Tests

  • cargo fmt --all -- --check
  • cargo test -p usage-lib --all-features hidden_commands_are_omitted_from_single_file_markdown
  • cargo test -p usage-lib --all-features docs::markdown::spec::tests

This pull request was generated by Codex.


Note

Low Risk
Documentation rendering only; behavior aligns hidden subcommands with existing index and flag/arg filtering.

Overview
Single-file Markdown reference generation no longer emits sections for commands marked hide=#true. The spec_template.md.tera subcommand loop now uses the same filter(attribute="hide", value=false) pattern already used on the index and for hidden args/flags.

A regression test asserts that a visible command still gets a ## heading while a hidden setup command and its help text never appear in render_spec() output.

Reviewed by Cursor Bugbot for commit 29355b4. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by CodeRabbit

  • Documentation

    • Single-command Markdown documentation now excludes commands marked as hidden.
    • Visible commands continue to appear in generated documentation.
  • Tests

    • Added regression coverage to verify hidden commands are omitted while visible commands remain documented.

@coderabbitai

coderabbitai Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f1fe2f8e-5ab7-4d9e-8c7d-ddfd58617587

📥 Commits

Reviewing files that changed from the base of the PR and between 3d69594 and 29355b4.

📒 Files selected for processing (2)
  • lib/src/docs/markdown/spec.rs
  • lib/src/docs/markdown/templates/spec_template.md.tera

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

Markdown spec generation now excludes commands with hide set to true. A regression test confirms that visible commands remain documented and hidden commands, including their help text, are omitted.

Changes

Markdown command visibility

Layer / File(s) Summary
Filter hidden commands and verify output
lib/src/docs/markdown/templates/spec_template.md.tera, lib/src/docs/markdown/spec.rs
The template filters hidden commands before rendering. The regression test confirms that visible commands appear and hidden commands do not.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 29355

This localized documentation change omits hidden commands from single-file Markdown references while preserving visible command output, with regression coverage included; no actionable merge-blocking risk remains beyond normal checks and review.

Poem

A rabbit checks the command parade
Hidden hops are kept in shade
Visible help springs into view
The Markdown trail stays clear and true
Tests nod softly: “All is right”

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: excluding hidden commands from Markdown documentation.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files. (1 skipped: 1 …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files. (1 skipped: 1 unsupported.)


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

Instruction counts

benchmark trend instructions Δ wall (min) Δ
markdown ▄▄▆▆▇█▅▆▆▁▂▁▂▃▃▂▃ 336,861,274 → 338,165,824 +0.39% 29.77 → 28.88ms -2.99%
startup ▄▄▃▃▃▄▁▁▁▃▃▃▃████ 910,478 → 910,415 -0.01% 0.98 → 0.93ms -5.19%

No instruction-count regression above 1%.

Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.

Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework stripped binary, bytes
usage 1321264
bpaf 2493280
clap 3101832
framework instructions, cold parse vs usage
usage 8309 —
clap 6315228 760x
bpaf 21909141 2636x
                                              min       p01       p10    median
usage-rs: argv -> struct                      406       412       418       425  ns
clap: build tree + parse -> struct         520785    521439    524310    531090  ns
bpaf: build parser + parse -> struct      1649858   1649858   1663199   1678332  ns

usage: argv -> struct                             465 ns      0.46 µs
clap: build tree + parse -> struct             531871 ns    531.87 µs
clap: parse -> struct, tree reused              23411 ns     23.41 µs
clap: build tree only                          325405 ns    325.41 µs

29355b482b08 vs 3d69594373f9 · measured on the runner, not pushed to the history.

@jdx
jdx merged commit d1edd88 into main Aug 25, 2026
9 of 11 checks passed
@jdx
jdx deleted the fix/markdown-hidden-commands branch August 25, 2026 15:15
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