doc: add cli documentation #15906
doc: add cli documentation #15906
Conversation
This roughs in some top level src-cli documentation, including an autogenerated reference.
|
Notifying subscribers in CODENOTIFY files for diff f99c191...ccaaa2e.
|
There was a problem hiding this comment.
This is really cool! But I think this should be its own top-level directory in the docs folder and the sidebar.
Why?
- I never would've looked for CLI documentation under "integrations"
- Once you're a few levels deep into the CLI docs the subsections are not highlighted anymore.
Edit: regarding the reference: I'm not 100% convinced whether auto-generated docs are great, but I think this is a great first step.
I agree with you, but I was a little nervous adding a brand new top level section for the CLI: it's important to us, but I'm not sure it's that important globally yet for Sourcegraph. @christinaforney, what do you think? |
I think it is important, especially since having it top-level would make it easier to discover other things we want to document in the future: versioning, releases, how to run src-cli in Docker, etc. These all fit nicely under explanations/how-tos/reference and it'd a shame if they are hidden in a sub-directory. |
|
I agree with @mrnugget - We can put this in the top level nav. I might end up doing some changing the left nav later, but the docs path should be |
doc/cli/references/doc.go
Outdated
| return errors.Wrap(err, "setting up go.mod") | ||
| } | ||
|
|
||
| goGet := exec.Command("go", "get", "github.com/sourcegraph/src-cli/cmd/src@581f9f532d890e6c2dc2ec2a130ab0d3d857e715") |
There was a problem hiding this comment.
I need to remove the explicit commit hash here before merging, but this is required right now to pull in sourcegraph/src-cli#387.
|
This now has reference generation via We might want to exclude this from the default |
|
Ah found one potential ever-changing value, especially in CI:
|
Ah, dang. I do have a horrifying idea on how to fix that, though. One moment. |
|
@eseliger Updated in conjunction with sourcegraph/src-cli@f48121d. |
|
Nice little hack, thanks for the prompt fix! |
There was a problem hiding this comment.
Good stuff!
We might want to exclude this from the default ./dev/generate.sh flow, since this is irrelevant 99% of the time, but let's see how bad this is first.
I agree with the "we might want" and think it doesn't need to be patched into ./dev/generate.sh in this PR. Feel free to add that in a follow-up though. (We could, for now, mention it in src-cli/DEVELOPMENT.md so that it's run when bumping the MinimumVersion)
|
|
||
| ### Install manually | ||
|
|
||
| 1. Download the latest [src_windows_amd64.exe](https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe) |
There was a problem hiding this comment.
Should this also mention that we prefer you use the version recommended by your Sourcegraph instance?
There was a problem hiding this comment.
I chose this intentionally: using the sourcegraph.com version means that we can provide a straight up link here, rather than requiring the user to construct their own URL based on their host name. Essentially, I want to optimise for time to first src command.
The catch here is obvious: if we make a change in a later src-cli version that breaks backward compatibility with older Sourcegraph versions, then this advice becomes dangerous, and probably turns into a support ticket.
This is getting into Versioning RFC fodder (for when I eventually have time to write it), but I'd prefer to move us explicitly to a model where the latest src-cli is always* safe for use with any reasonable Sourcegraph version, rather than users having to figure out what the right version for their Sourcegraph is.
I'm not opposed to adding a note about getting the recommended version for your Sourcegraph instance from some link, but I'd prefer to keep the default instruction to download the most recent version for simplicity. Another option would be to add a proper download page to Sourcegraph: we could link it from the footer, and do some autodetection based on the user agent to suggest the most likely binary — that would be easier to document, I think, that a DIY URL.
I'm going to go ahead and merge this PR (once I've addressed the other remaining feedback), since the release is tomorrow, but I hear you, don't consider this conversation closed, and we should iterate more on this. 😄
* Yes, that's a big word, and I'm a little scared of it. 😄
Co-authored-by: Thorsten Ball <mrnugget@gmail.com>
Yep, that's what I've done in sourcegraph/src-cli#391. |
This roughs in some top level src-cli documentation, including:
src logindocumentation.I'm on the fence about the utility of the reference: it's auto-generated from src-cli via an experimental
doccommand added in sourcegraph/src-cli#387, but we don't really have the structured data in src-cli right now to drive a good Markdown experience. Opinions welcome.I've pushed this to https://docs.sourcegraph.com/@aharvey-login-docs/cli (alas, I forgot until after I'd opened this PR that docsite can't handle slashes in branch names, so I'll have to try to keep that up to date separate to this PR by double pushing).
This closes #14528 and closes #15882.