Skip to content

fix/help: Generate help command list from registered commands - #1377

Open
marcleblanc2 wants to merge 1 commit into
remove-teams-commandfrom
help-from-registered-commands
Open

fix/help: Generate help command list from registered commands#1377
marcleblanc2 wants to merge 1 commit into
remove-teams-commandfrom
help-from-registered-commands

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Generate help text from the command registries

Test plan

  • go run ./cmd/src doc -o /tmp/x vs the base branch: same 77 files, only version.md gains a summary line
  • Each of these fails a named test: dropping a command from rootCommands(), removing a command's description, reintroducing the maps.Copy argument swap
  • go test ./cmd/src/... passes

Stack

Merge in order (FE-502):

  1. src-cli#1375 src doc: subcommand pages for debug/search-jobs/snapshot, fix root index
  2. src-cli#1376 remove src teams
  3. src-cli#1377 generate src help from registered commands
  4. src-cli release containing the above
  5. sourcegraph#15528 bump the src-cli pin, check in the new src doc output
  6. sourcegraph#15529 make the docs sync mirror doc/cli/references instead of copying over it

@marcleblanc2 @ampagent
help: generate the 'src help' command list from the registered commands
51fe0a4 
The "The commands are:" block in 'src help' was a hand-maintained string in
main.go. It had drifted from the registered commands: 'debug', 'snapshot',
and 'lsp' were never added, and the codeowners description differed from
the command's own Usage.

Build the list at runtime from both registries (legacy 'commands' and
urfave/cli 'migratedCommands'). Legacy commands get a 'description' field
and a 'hidden' flag; 'src doc' uses the same flag instead of hard-coding
the names to skip. 'version' gets a Usage so it has a description.

Tests keep the three lists apples-to-apples:
- 'src help' == registered commands (TestHelpListsAllRegisteredCommands)
- 'src doc' root index == 'src help' == registered (TestDocRootIndexMatchesHelp)
- every visible command has a description (TestRootCommandsAreWellFormed)

Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1
Co-authored-by: Amp <amp@ampcode.com>
This was referenced Sep 9, 2026
Open
Open
Merged
@marcleblanc2 marcleblanc2 changed the title help: generate the 'src help' command list from the registered commands, and test help == docs fix/help: Generate help command list from registered commands Sep 9, 2026
marcleblanc2 added a commit to sourcegraph/docs that referenced this pull request Sep 11, 2026
@marcleblanc2 @ampagent
docs/cli: Add missing doc pages for src-cli commands (#1889)
b6a21bb 
Part of [FE-502](https://linear.app/sourcegraph/issue/FE-502). **Step 4
of 4** in a cross-repo stack, but **mergeable now** — it pre-seeds what
the generated-docs sync will eventually write, so the live reference
gets fixed without waiting on a src-cli release.

## Why

The `src` CLI reference is generated by `src doc` and synced here by
sourcegraph/sourcegraph's `sync/generated-docs` job. Two generator bugs
(fixed in sourcegraph/src-cli#1375) left this reference incomplete:

- `search-jobs`, `debug` and `snapshot` were never registered in the
generator's `commanders` map, so each is a single page with only the
group help; their 16 subcommands have no reference pages. (The 8
`search-jobs/*.mdx` pages here were hand-written by Travis Lyons in May
2025 to paper over this; nothing links to them.)
- `index.mdx` lists only the 8 urfave/cli commands (`abc`, `api`,
`auth`, `codeowners`, `login`, `orgs`, `users`, `version`) — `batch`,
`repos`, `search`, `config`, etc. are missing from
https://sourcegraph.com/docs/cli/references today.

## What

- `index.mdx`: lists all 19 top-level commands.
- `debug/{index,compose,kube,server}.mdx`,
`snapshot/{index,databases,restore,summary,test,upload}.mdx`: new.
- `search-jobs/index.mdx`: new;
`search-jobs/{cancel,create,delete,get,list,logs,restart,results}.mdx`:
hand-written pages replaced by generated ones (same usage text, plus a
flags table; the `<p className="subtitle">` blurbs go away since the
generator doesn't emit them).
- Deleted `debug.mdx`, `search-jobs.mdx`, `snapshot.mdx`.
- Deleted `teams.mdx` and dropped `teams` from `index.mdx`: teams were
removed in Sourcegraph 7.0 and sourcegraph/src-cli#1376 removes the
command, so the generator no longer emits this page. No redirect (same
call as #1886). The sync job never deletes files, and in contentlayer
routing a flat `foo.mdx` shadows `foo/index.mdx` (the same bug #1886
fixed for `auth.mdx`/`codeowners.mdx`), so these have to go by hand for
the new index pages to be reachable.

Content was produced by running the patched generator (src-cli `main` +
#1375) and the same `tools/md2mdx` conversion the sync uses, so the sync
PR that follows sourcegraph/sourcegraph#15528 should be a no-op for
these paths.

No redirects: the three deleted URLs
(`/cli/references/{debug,search-jobs,snapshot}`) keep resolving, now to
the new index pages.

## Stack

1. sourcegraph/src-cli#1375 — generator fix + tests;
sourcegraph/src-cli#1376 (stacked) — remove `src teams`;
sourcegraph/src-cli#1377 (stacked) — `src help` generated from
registered commands, tests help == docs
2. src-cli 7.7.0 release (none since 7.6.0; blocks 3)
3. sourcegraph/sourcegraph#15528 — pin bump + `OUTPUT_FILES` +
regenerate (draft until 2)
4. **this PR**
5. sourcegraph/sourcegraph#15529 — make the docs sync mirror
`docs/cli/references/` so removed commands disappear automatically
(merge after 3 and this PR)

Related: #1886 (removed 28 stale pages for commands that no longer
exist).

## Test plan

`npx contentlayer build` → 528 documents; routes resolve to the intended
files:

```
/cli/references/debug        <- cli/references/debug/index.mdx
/cli/references/search-jobs  <- cli/references/search-jobs/index.mdx
/cli/references/snapshot     <- cli/references/snapshot/index.mdx
```
plus the 16 subcommand routes. (The `ERR_INVALID_ARG_TYPE`/clipanion
stack trace during the build is pre-existing on `main`.)

## Amp threads

- [Stale command
docs](https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1)

---------

Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2
marcleblanc2 added this pull request to stack #1380 September 25, 2026 04:21
@marcleblanc2
marcleblanc2 removed this pull request from stack #1380 September 25, 2026 04:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@marcleblanc2