Create command-reference.md #445
Conversation
|
@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 |
|
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 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
force-pushed
the
command-reference-docs
branch
from
10be898 to
2a546c9
Compare
|
@katiewasnothere addressed all comments |
| @@ -0,0 +1,709 @@ | |||
| # Container CLI Command Reference | |||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
wlan0
force-pushed
the
command-reference-docs
branch
from
2a546c9 to
c8ed946
Compare
wlan0
force-pushed
the
command-reference-docs
branch
from
c8ed946 to
1df604b
Compare
3 participants
Fixes #375