docs/cli: Add missing doc pages for src-cli commands - #1889
Open
marcleblanc2 wants to merge 2 commits into
Open
Conversation
…; list all commands in index Pre-seeds the output of the fixed `src doc` generator (sourcegraph/src-cli#1375) so the CLI reference is correct now rather than after the next src-cli release and docs sync: - index.mdx lists all 20 top-level commands again (was only the 8 urfave/cli ones since src-cli#1304). - debug/, snapshot/: new index + subcommand pages (9 files). - search-jobs/: new index; the 8 hand-written subcommand pages are replaced by the generated equivalents (same usage text, plus a flags table). - Delete the flat debug.mdx, search-jobs.mdx, snapshot.mdx. The sync job never deletes, and these would shadow the new <group>/index.mdx in contentlayer routing. Files were produced with the same md2mdx conversion the sync uses; the sync/generated-docs PR that follows sourcegraph/sourcegraph#15528 should be a no-op for these paths. Part of https://linear.app/sourcegraph/issue/FE-502 Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Teams were removed in Sourcegraph 7.0; src-cli#1376 removes the command. No redirect, per the same call as #1886. Part of https://linear.app/sourcegraph/issue/FE-502 Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1 Co-authored-by: Amp <amp@ampcode.com>
marcleblanc2
changed the title
marcleblanc2
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of 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
srcCLI reference is generated bysrc docand synced here by sourcegraph/sourcegraph'ssync/generated-docsjob. Two generator bugs (fixed in sourcegraph/src-cli#1375) left this reference incomplete:search-jobs,debugandsnapshotwere never registered in the generator'scommandersmap, so each is a single page with only the group help; their 16 subcommands have no reference pages. (The 8search-jobs/*.mdxpages here were hand-written by Travis Lyons in May 2025 to paper over this; nothing links to them.)index.mdxlists 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).debug.mdx,search-jobs.mdx,snapshot.mdx.teams.mdxand droppedteamsfromindex.mdx: teams were removed in Sourcegraph 7.0 and chore: Remove deprecatedsrc teamscommands src-cli#1376 removes the command, so the generator no longer emits this page. No redirect (same call as docs/cli: Remove doc pages for removed src-cli commands #1886). The sync job never deletes files, and in contentlayer routing a flatfoo.mdxshadowsfoo/index.mdx(the same bug docs/cli: Remove doc pages for removed src-cli commands #1886 fixed forauth.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 sametools/md2mdxconversion 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
src teamscommands src-cli#1376 (stacked) — removesrc teams; fix/help: Generate help command list from registered commands src-cli#1377 (stacked) —src helpgenerated from registered commands, tests help == docsOUTPUT_FILES+ regenerate (draft until 2)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:plus the 16 subcommand routes. (The
ERR_INVALID_ARG_TYPE/clipanion stack trace during the build is pre-existing onmain.)Amp threads