Picocli: Generate MarkDown or AsciiDoc documentation

[charphi]

As picocli generates already the command line completion in bash, it should be possible to auto generate a documentation (in markdown) so that it is always uptodate with the code.

[remkop]

Yes good idea. I thought generating documentation in man page format or HTML would be useful.
I hadn't thought about markdown.
Pull requests are always welcome!

[RobertZenz]

As a note, Pandoc can be used to convert Markdown into a variety of files (including HTML and man pages). So Markdown seems like quite a good choice here, because one can simply string it together with Pandoc to get the desired output they want.

[cbeams]

Related to the Pandoc comment above, I'd like to see picocli grow the ability to produce manpage-formatted output exactly like what git help <subcommand> produces. I believe Git is simply delegating to man git-<subcommand> here, but picocli could bake this generation in using Markdown / Pandoc etc. With that said, I'd love to see someone put together a first-class approach to generating / publishing manpages for commandline JVM apps; then picocli could (optionally) delegate to them just as Git does, such that for a picocli-based app named foo, foo help subcommand would produce precisely the same output as man foo-subcommand.

[remkop]

All of this sounds very cool! I won’t be able to work on this aspect for a while. If anyone wants to provide a pull request, that would be great!

[NicolasMassart]

Any news on that ? I was thinking about outputting a semantically rich help like in JSON or YAML so we could have the raw data to transform it in MD, HTML, RST, LATEX even the CLI text help or whatever... I was thinking about docopt at the beginning, but it doesn't enable an easy parsing to format the output.
So perhaps more like Swagger OpenAPI but for CLI. I did not find anything like that yet.

[remkop]

Yes, there is a small update: the picocli-codegen module in the master branch now contains an annotation processor (#500) to create picocli CommandSpec model objects _at compile time_. The idea is to be able to do more at compile time, including generating documentation.

Also, I am currently thinking (#459) to generate documentation in AsciiDoc instead of MarkDown. There is some nice (tooling)[https://asciidoctor.org] to convert AsciiDoc to HTML, PDF, and even Unix man page format.

But if anyone wants to contribute code that generates MarkDown instead of AsciiDoc, that would be welcome!

[nicobrevin]

As a first step, I'd be happy to just have a utility that can take an unparsed command line and generate mardown etc - doing this at compile time would be nice, but that's a whole new level of complexity. Most projects are CLIs, and so should be able to support a my-app --help --as-markdown options to produce the help?

[remkop]

One way to make progress on this would be to add a utility class to the picocli-codegen module. Given a CommandSpec object, this utility would return a String with the usage help in either AsciiDoc or MarkDown (these formats are very similar).

@nicobrevin Do you think you’ll be able to provide a pull request for this?

[remkop]

@charphi @RobertZenz @cbeams @NicolasMassart @nicobrevin
An initial version of this is now available in master: the picocli.codegen.docgen.manpage.ManPageGenerator class in the picocli-codegen module generates AsciiDoc, which can then be converted to manpage by asciidoctor.

You can test by checking out the latest master and building with:

gradlew clean publishToMavenLocal

That should publish picocli-4.2.0-SNAPSHOT to your local .m2 Maven cache. You can then try this in a project that uses the info.picocli:picocli:4.2.0-SNAPSHOT dependency.

See this comment for details on converting the output to man pages.

Known issues:

• [x] custom option sections (arggroup option sections) are still ignored
• [x] embedded markup like @|bold hello|@ in descriptions and header/footer text is rendered as ANSI escape codes and not yet converted to AsciiDoc markup
• [x] @<filename> is included in the synopsis but not in the ARGUMENTS section

Update: the above known issues are all resolved now in master.

Feedback very welcome!

[remkop]

Previews of generated man pages in HTML format are now live here: https://picocli.info/man/

[remkop]

@charphi @RobertZenz @cbeams @NicolasMassart @nicobrevin, All,

picocli 4.2.0 has been released, including this functionality. Enjoy!

[charphi]

Thank you! The result is much better than my initial idea ;)