Generate CLI docs from Go code

[zeke]

This PR generate CLI reference docs programmatically from the Go source code using cobra/doc.

View the docs

https://github.com/replicate/cog/blob/077efdfda59d207ed58601c2b4513e33cda10e00/docs/cli.md

Generate the docs

script/build-cli-docs

To Do

• Figure out how to get cobra/docs to fold all CLI docs into one markdown file.
• Improve existing long and example docs in Go commands
• Configure mkdocs.yml to include CLI docs in https://cog.run site nav
• Figure out if we can do all the shell-script silliness in a single Go script instead and maybe a make command
• Update build process (and CONTRIBUTING docs) to generate docs
• docs/cli.md is an artifact of the build process. How do we get it checked into the repo?

Resolves #433

[zeke]

Possibly useful prior art mentioned by @marcusmartins:

https://github.com/infrahq/infra/blob/a7a3b3b48c58b999dc5cc88fcd467b975dafffdf/internal/docgen/cli.go#L102

[zeke]

This script is a bit heinous. Would love to make it all happen more glamorously in a single Go script, but I'm not a good enough gopher to make that happen.

Halp!?

[marcusmartins]

I think it would make sense to move the docs generation to a dedicated command (see comment above) and add the steps here to the command so it's self container.

I can take a stab at it later today.

[timfallmk]

Agreed that a separate generate-docs command, in a similar sense to autocompletion scripts would work well here. There's inspiration from the cobra docs themselves. a la https://www.emmanuelgautier.com/blog/snippets/go-cobra-docgen

[zeke]

This is ready for eyes!

It works, but there a few outstanding issues to get it over the finish line. Could use some help from someone with Gopher skills and knowledge of where this new docs build process should slot into the dev/release cycle.

[marcusmartins]

Left a few comments. I am happy to look into it today.

[marcusmartins]

This should be moved to a separate command. Otherwise, it creates the docs everytime the main get invoked

[marcusmartins]

I think it would make sense to move the docs generation to a dedicated command (see comment above) and add the steps here to the command so it's self container.

I can take a stab at it later today.

[marcusmartins]

Are you still using the new dependencies here?

[zeke]

I'm actually not sure.. I didn't add them manually. Maybe they got added by cobra/doc?

[zeke]

Converting this back to a draft. Still worth pursuing, but not a high priority.

[aknoerig]

Asking kindly for someone to push this across the finish line. As a newbie to cog, the lack of systematic docs makes it a bit confusing to get started. Everything centers around the cog CLI, but there's no proper reference for it. It would help a lot to get a better understanding of the cog capabilities, plus I'd really like to know what a command will do before I execute it in my shell. Thanks!

[aron]

Removing @replicate/cog as the reviewers for the moment as this currently shows up in the review reminders and is non-actionable.