Create command-reference.md

[wlan0]

Fixes #375

[katiewasnothere]

@wlan0 could we use something like https://github.com/apple/swift-argument-parser/blob/main/Tools/generate-manual/GenerateManual.swift to generate man pages instead? I'd like something that we don't need to manually update

[wlan0]

@wlan0 could we use something like https://github.com/apple/swift-argument-parser/blob/main/Tools/generate-manual/GenerateManual.swift to generate man pages instead? I'd like something that we don't need to manually update

Let’s skip man pages entirely. Every detail a user would look for in man container - subcommands, flags, examples already comes straight from our source of truth via container --help.

Our commands are largely static and any future changes automatically flow into --help.

Let’s keep Markdown as the only human-readable doc format and rely on container --help for terminal users

[katiewasnothere]

I think overall we should keep the language/descriptions of the subcommands and options the same as in the help output. Otherwise the difference in language could become confusing (for example, the comment above about referring to "tailing the logs" as using the --follow option while also having an option on the same command that operates like tail in linux).

IMO this doc really should just be the help output with a bit more description as needed (for example, the description of the run command in this PR is very helpful and augments what's in the help output) and some example use cases as you already have.

[wlan0]

@katiewasnothere addressed all comments

[jglogan]

Do we need a PR template that includes a reminder (or checklist if we also want a reminder for unit/integration tests and anything else) for updating docs?

[jglogan]

if we wanted a more closed-form approach to this (one that we could validate via build), swift-argument-parser offers an --experimental-dump-help that writes all help output to a JSON file. If we wanted to merge informative content with the normative material from the dump, we could maintain the informative material as a set of files that could be JSON patched in, and then rendered to markdown or whatever we want

[katiewasnothere]

Another option is argument parser's generate-docc-reference. Doesn't look like this plugin is feature rich enough for us yet, but maybe in the future it will be.

[jglogan]

One nit, see comment.