Improve navigation for picocli-generated manual pages

[rsenden]

Our picocli-based application provides a relatively large hierarchy of sub-commands, with a command structure like the following: our-app <module> <entity> <operation>. Here, <module> and <entity> are non-runnable commands used to organize the command tree, and <operation> represents runnable commands. In total, we currently have 346 non-hidden commands, of which 281 are runnable <operation> commands, organized in 8 modules and a variable number of entities per module.

This means that picocli generates 346 asciidoc manual pages, which we convert to 346 individual HTML pages (for offline use) and Jekyll pages (for use on github.io). These pages are relatively difficult to navigate; from the top-level our-app manual page, users need to click a sub-command link to navigate to some <module>, then click another link to navigate to some <entity> within that module, and finally click on another link to end up on an <operation> manual page. This also makes it difficult for users to get a complete overview on what functionality is covered/not covered by our application (we do provide an our-app util all-commands list command, but obviously the output is only available at runtime, not in documentation).

Following lists some ideas that came to mind for improving navigation, but not sure whether any of this is possible with current picocli/Asciidoctor functionality, or how difficult it would be to implement such functionality:

• Apart from direct sub-commands, include a full hierarchy of sub-commands on each manual page. For example, the top-level our-app manual page would list the full tree of all sub-commands (with links to corresponding manual page), the our-app module1 manual page would list the full tree of sub-commands for module1, ...
• Have a breadcrumb navigation bar on each manual page, for example allowing to directly navigate from our-app mod1 ent1 op1 to either our-app, our-app mod1 or our-app mod1 ent1 parent manual pages. Even better would be to have the breadcrumb support drop-down menus to navigate to siblings, i.e., the our-app mod1 breadcrumb item would show a drop-down for navigating to mod2 and mod3.
• Alternatively, have an option to generate a single-page document with proper table of contents that lists all manual pages.

Ideally, we'd want to improve navigation for both offline (HTML) and online (Jekyll) pages, but improving just the online documentation based on GitHub Jekyll capabilities would be a good start.