Generate documentation for command line interfaces

[renancaraujo]

Some people (like me) love publishing some command line apps on pub. Happens that often, such packages do not include a public API as code. Rather, the API is through commands and options to be executed in the terminal. Almost always using package:args.

To document such CLIs, maintainers must resource to the old ways and keep files such as the README up to date (manual work 😱).

It would be awesome if https://pub.dev/documentation/<package_name>/latest/ would also present pages with the commands available and their respective help message (often obtained via --help).

[srawlins]

Cool idea. I think there could be some configuration that we could provide. Tricky to read the --help text of a script inside a package-being-documented... because you have to run the code to produce that text.

[renancaraujo]

@srawlins you can obtain it programmatically if the CLI was built using package:args's CommandRunner, which keeps a tree of commands, subcommands, and options.
I did have to map that programatically to build cli_completion, so maybe dartdoc can use the same approach?

[srawlins]

That's what I mean, I think. You cannot statically determine what command documentation is. You have to programmatically determine it (run the code), executing calls to addCommand etc.