search

remkop / picocli

Picocli is a modern framework for building powerful, user-friendly, GraalVM-enabled command line apps with ease. It supports colors, autocompletion, subcommands, and more. In 1 source file so apps can include as source & avoid adding a dependency. Written in Java, usable from Groovy, Kotlin, Scala, etc.
https://picocli.info
Apache License 2.0
4.93k stars 424 forks source link

option to generate single html/man page #1227

Open maxandersen opened 4 years ago

maxandersen commented 4 years ago

would be awesome if the man page generator would be able to generate a single html page instead of per subcommand. The current end result ends up being very fragmented.

reason: https://github.com/jbangdev/jbang/pull/444

remkop commented 4 years ago

This looks very interesting and I am certainly open to improving this.

Anyone able to provide a pull request?

remkop commented 4 years ago

I haven’t given any thought to what the structure of the generated AsciiDoc would become. Simple concatenation? What about nested sub-subcommands?

What about links, simply make all command names links to other sections in the same document? Do subcommands link back to their parent?

Anything else worth considering that doesn’t come up for single command doc pages?

maxandersen commented 4 years ago

Includes would work as long as follow same convention.

My thinking is to get to something like manual at cli.github.com.

remkop commented 4 years ago

Looking at https://cli.github.com/manual/ , I see each command and subcommand has a separate page, and the Table of Contents (TOC) navigation bar on the left brings them all together. The TOC especially is nice: it expresses the command hierarchy and is intuitive to navigate.

One way I can see this can be done with AsciiDocter is to have a single document for each top-level command. This doc can have a section for each subcommand, sub-sections for each sub-subcommand, etc. AsciiDocter's table of contents feature would generate the navigation bar on the left. The contents of that document could be just titles for each section and subsection, and the contents of each of these sections could be an include that points to the file currently generated by picocli-codegen.

@grumpyf0x48 I see you have been working on https://github.com/jbangdev/jbang/issues/363 and https://github.com/jbangdev/jbang/pull/444, would you be interested in upstreaming some of your work to do this in picocli-codegen directly?

remkop commented 3 years ago

Note that https://github.com/remkop/picocli/pull/1340 will improve this a little bit in the upcoming picocli release.

bentatham commented 2 years ago

This would be great for a single PDF file, as well as single-page HTML.

remkop commented 2 years ago

@bentatham Do you feel like providing a pull request for this?