Skip to content

feat/doc: add src doc -json for a structured command reference - #1404

Closed
taras-yemets wants to merge 1 commit into
mainfrom
taras/src-doc-yaml
Closed

taras-yemets wants to merge 1 commit into
mainfrom
taras/src-doc-yaml

Conversation

@taras-yemets

@taras-yemets taras-yemets commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

src doc -json -o FILE writes the whole command reference as one JSON file: a tree of all visible commands with their summary, usage, help, flags, and subcommands.

The new docs site in sourcegraph/sourcegraph will use it after the next release. With data instead of finished Markdown, the site decides the layout: one page per command, all commands on one page, a different style, and so on.

The format is our own and small, inspired by gcloud's CLI tree. It covers both command kinds here (flag.FlagSet and urfave/cli), and the Cobra-based src in the monorepo can write the same tree later. JSON, so the docs site needs no extra parser. The Markdown output doesn't change.

Test plan

  • New TestDocJSONMatchesMarkdown: the JSON has exactly the commands that have Markdown pages.
  • src doc -o output is byte-identical to main.
  • Rendered the JSON with the new docs site locally: all 76 command pages and the sidebar look right.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

@taras-yemets
taras-yemets force-pushed the taras/src-doc-yaml branch 2 times, most recently from f7f345b to 170e9d2 Compare November 10, 2026 15:54
@taras-yemets taras-yemets changed the title feat/doc: add src doc -yaml for a structured command reference feat/doc: add src doc -json for a structured command reference Nov 10, 2026
@taras-yemets
taras-yemets force-pushed the taras/src-doc-yaml branch 2 times, most recently from 3008be3 to 6f0da1d Compare November 10, 2026 16:14
The new Sourcegraph docs site needs the CLI reference as data, so that it
can lay out the pages as it wants. 'src doc -json -o FILE' writes one JSON
tree of all visible commands, with their summary, usage, help, flags, and
subcommands.

Copy link
Copy Markdown
Contributor Author

Closing for now. The docs site will use the existing src doc output (sourcegraph/sourcegraph#18808) and, later, a docs command in the new cmd/src CLI. We can reopen this if we need it sooner.

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