cue icon indicating copy to clipboard operation
cue copied to clipboard

cmd/cue: have a single source of truth for cli docs

Open cueckoo opened this issue 4 years ago • 2 comments
trafficstars

Originally opened by @mpvl in https://github.com/cuelang/cue/issues/9

This likely means that the cli docs should be generated from the tool code.

cueckoo avatar Jul 03 '21 10:07 cueckoo

My 2c: I think we should start moving towards all canonical documentation being on the website. Go already started doing this with https://go.dev/ref/mod, for example. Then go help modules is a short summary with HTTP links, rather than dozens of pages printed out to the terminal, which overwhelm almost anyone.

I also feel like markdown-like styling is helpful. Headers, links, code blocks, and so on. That is technically possible on the terminal with something like man pages, but I think web pages are generally more accessible to the majority of users, particularly when there is so much information.

We could and should keep cue help, but its contents should be limited in size and complexity. Packagers or distros could always ship the HTML pages alongside cmd/cue so that all the docs are available offline.

mvdan avatar Jun 13 '23 16:06 mvdan

Adjacent to this issue, https://alpha.cuelang.org/docs/reference/cli/ is now available.

jpluscplusm avatar Dec 11 '23 22:12 jpluscplusm

I believe we should close this due to the work that has already happened and in favor of automating the structure of https://cuelang.org/docs/reference/cli/ via https://github.com/cue-lang/cue/issues/3204.

mvdan avatar Jun 07 '24 11:06 mvdan