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, which main.go calls before fang.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 cli and glab ci config compile are deeper), and TestTopLevelCommandsInheritRootHelpFunc fails if one starts to.
    • Annotations are not inherited, so a subcommand doesn't repeat its parent's sections, which matches RootHelpFunc.
    • RootHelpFunc builds its ARGUMENTS and ENVIRONMENT VARIABLES entries from the same AnnotationSections, so the annotation keys and titles are defined once.
  • Changes the glab duo cli binary-status footer to chain to its parent's help func instead of the root's, so it keeps the sections. glab ci config compile already chains to its parent.
  • Makes gen-docs write the same sections (## Arguments, ## Environment variables) as plaintext blocks on each subcommand page. The texts mix plain NAME: description lines 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.

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) runs child --help through a real fang.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 cli help 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 with help:arguments or help:environment (24 today, 14 of them glab dependency-firewall commands) shows its sections. It fails if a command's own help func stops chaining to its parent: making the glab duo cli footer 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. Giving glab api its own help func makes it fail with glab api sets its own help func, which help.AppendAnnotationSections would replace.
  • TestRootHelpFuncAnnotationSectionsMatchAnnotationSections (internal/commands/help): RootHelpFunc renders the same sections, and none for an empty annotation.
  • A built binary, before and after, gives the results in the table above. glab help mr shows ARGUMENTS too. glab ci config compile --help still hides --repo.
  • go test -race passes on the help, gen-docs, duo/cli, cmd/glab, ci/config/compile, internal/commands and df packages. golangci-lint and comment-overlap report nothing. make gen-docs was 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 from theme.FangColorScheme.
Edited by Arpit Gogia

Merge request reports

Loading
Loading