Repository navigation
feat/doc: add src doc -json for a structured command reference - #1404
Closed
taras-yemets wants to merge 1 commit into
Closed
taras-yemets wants to merge 1 commit into
taras-yemets wants to merge 1 commit into
Conversation
taras-yemets
force-pushed
the
taras/src-doc-yaml
branch
2 times, most recently
from
November 10, 2026 15:54
f7f345b to
170e9d2
Compare
src doc -yaml for a structured command referencesrc doc -json for a structured command reference
taras-yemets
force-pushed
the
taras/src-doc-yaml
branch
2 times, most recently
from
November 10, 2026 16:14
3008be3 to
6f0da1d
Compare
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.
taras-yemets
force-pushed
the
taras/src-doc-yaml
branch
from
November 11, 2026 13:15
6f0da1d to
1ee58a4
Compare
Contributor
Author
|
Closing for now. The docs site will use the existing |
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
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.
src doc -json -o FILEwrites 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.FlagSetand urfave/cli), and the Cobra-basedsrcin 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
TestDocJSONMatchesMarkdown: the JSON has exactly the commands that have Markdown pages.src doc -ooutput is byte-identical tomain.