fix(help): show argument and environment variable sections again
Description
Command help hasn't shown the help:arguments and help:environment annotations since fang took over help rendering (6f2e7361). fang.Execute replaces the root command's help func with fang's renderer (fang.go:140 in charm.land/fang/v2 v2.0.1), and that renderer ignores annotations. help.RootHelpFunc was the only code that rendered them, and it never runs in production. The generated pages for subcommands never rendered the annotations either. Commands that documented their environment variables or argument formats there showed neither in --help nor in the docs.
This MR:
- Adds
help.AppendAnnotationSections, whichmain.gocalls beforefang.Execute.- It gives each top-level command a help func that runs the root help func (fang's renderer), then writes the command's ARGUMENTS and ENVIRONMENT VARIABLES sections in fang's layout. The sections go to the command's
OutOrStdout, the writer fang renders the help body to, so they stay together when a command's output is redirected. IOStreams only picks the colors. - Deeper commands inherit it.
- It replaces any help func already set on a top-level command, so top-level commands must not set one. None does today (
glab duo cliandglab ci config compileare deeper), andTestTopLevelCommandsInheritRootHelpFuncfails if one starts to. - Annotations are not inherited, so a subcommand doesn't repeat its parent's sections, which matches
RootHelpFunc. RootHelpFuncbuilds its ARGUMENTS and ENVIRONMENT VARIABLES entries from the sameAnnotationSections, so the annotation keys and titles are defined once.
- It gives each top-level command a help func that runs the root help func (fang's renderer), then writes the command's ARGUMENTS and ENVIRONMENT VARIABLES sections in fang's layout. The sections go to the command's
- Changes the
glab duo clibinary-status footer to chain to its parent's help func instead of the root's, so it keeps the sections.glab ci config compilealready chains to its parent. - Makes gen-docs write the same sections (
## Arguments,## Environment variables) asplaintextblocks on each subcommand page. The texts mix plainNAME: descriptionlines and Markdown lists, and a code block shows both exactly as the terminal does. This regenerates 24 pages.
| Command | ARGUMENTS before / after | ENVIRONMENT VARIABLES before / after |
|---|---|---|
glab api --help |
– | missing / shown |
glab artifact-registry login --help |
– | missing / shown |
glab config path --help |
– | missing / shown |
glab duo cli --help |
– | missing / shown |
glab orbit --help |
– | missing / shown |
glab help dependency-firewall <manager> (14 package-manager commands) |
– | missing / shown |
glab mr --help, glab issue --help, glab incident --help, glab snippet --help, glab attestation --help |
missing / shown | – |
Not changed: glab --help itself. fang sets the root help func as Execute starts, so nothing glab installs on the root survives. The root's environment variable list and feedback section therefore still aren't shown in the terminal. The root reference page already links to the full environment variable table in configuration.md.
glab dependency-firewall <manager> --help still prints the package manager's own help, because those commands pass every argument through to it (DisableFlagParsing). Their section shows in glab help dependency-firewall <manager> and on their docs pages.
Related Issues
No issue. Found while working on !4150 (merged), where the new help:environment annotation on the glab dependency-firewall package-manager commands didn't appear in their help.
How has this been tested?
TestAppendAnnotationSectionsFollowFangHelp(internal/commands/help) runschild --helpthrough a realfang.Execute, with the command's output writer separate from the IOStreams buffer. It checks that ARGUMENTS and ENVIRONMENT VARIABLES follow fang's USAGE section in the same writer, with their bodies, that nothing goes to IOStreams, and that a subcommand without annotations shows neither. With the sections written through IOStreams, the version before review, it fails.TestAppendBinaryStatusFooter_KeepsAnnotationSections(internal/commands/duo/cli):glab duo clihelp shows both the environment section and the binary-status footer.TestGenMarkdownCustomRendersHelpAnnotations(cmd/gen-docs): pages for annotated commands have both sections, and pages for other commands have neither.- All three failed before the fix because the sections were missing. They pass after it.
TestAnnotatedCommandHelpShowsAnnotationSections(internal/commands) builds the real command tree, installs the wrapper, and checks that every command withhelp:argumentsorhelp:environment(24 today, 14 of themglab dependency-firewallcommands) shows its sections. It fails if a command's own help func stops chaining to its parent: making theglab duo clifooter call the root help func makes it fail.TestTopLevelCommandsInheritRootHelpFunc(internal/commands) builds the real command tree and checks that every top-level command inherits the root's help func, compared by function pointer. Givingglab apiits own help func makes it fail withglab api sets its own help func, which help.AppendAnnotationSections would replace.TestRootHelpFuncAnnotationSectionsMatchAnnotationSections(internal/commands/help):RootHelpFuncrenders the same sections, and none for an empty annotation.- A built binary, before and after, gives the results in the table above.
glab help mrshows ARGUMENTS too.glab ci config compile --helpstill hides--repo. go test -racepasses on thehelp,gen-docs,duo/cli,cmd/glab,ci/config/compile,internal/commandsanddfpackages. golangci-lint and comment-overlap report nothing.make gen-docswas run, and the regenerated pages are in the commit.
Unapplied review findings
- P3 —
internal/commands/help/annotations.go:59— The new section titles are bold only. fang's titles also use the color scheme's title color, so on a color terminal ARGUMENTS and ENVIRONMENT VARIABLES don't match USAGE and FLAGS. fang doesn't export its styles, so matching them means rebuilding the title style fromtheme.FangColorScheme.