Auto-generate manpage, help docs, etc.

[joshtriplett]

Maintainer notes:

• Blocked on [modular] Decouple help format from help generation #2914 for decoupling help information gathering from formatting
• help2man can be a source of inspiration for how to integrate this into a users process

---

I'd love to have support to generate a manpage. This would use a mechanism and infrastructure similar to #376. Additional functions to override or augment portions of the generated manpage could come later, but I think with relatively few additions this could become an incredibly useful mechanism.

• The manpage title should default to the bin_name value.
• The section should default to 1.
• The NAME section should default to bin_name \- about, where about is the string set by .about.
• The SYNOPSIS section should contain the usage strings for the command and every subcommand.
• The DESCRIPTION section would need some new paragraph-style information provided (also usable as a more structured .before_help).
• The "OPTIONS" section should document the flags and args for the top-level command.
• If the command has subcommands, a "SUBCOMMANDS" section should document each subcommand in a sub-section.
• The AUTHORS section should contain the author information, if provided.
• The SEE ALSO section would need some new mechanism to populate it.

I'd be happy to help with manpage markup, once I see the details of the mechanism used in #376.

[kbknapp]

I like this idea! I'll have a better idea about what all it would take once I finish #376 but I think it could be done. And if nothing else, it'll at least give a really good starting point that one could then tweak manually with little effort.

[joshtriplett]

Absolutely. I'm also hoping that, similar to help2man (which doesn't handle most of what clap can do), this could support providing arbitrary additional documentation to integrate into the generated manpage. That would allow maintaining information in only one place (such as options and their documentation).

[hgrecco]

I was thinking about the same thing recently and I think we can reuse much of the infrastructure done for the templated help. But I would also like to propose a different way to generate the man page (and access the completion). I am opening another issue for this.

[kbknapp]

Addressing this issue soon. I'd like to get the ability to generate man pages, help docs, etc. For the help docs, I'd especially like to be able to generate based off a template exactly like App::template works. Except recursively going through subcommands. The template would allow doing things like markdown, etc.

Also, for help docs I'd like to choice to split the files or use a single document.

[matthiasbeyer]

As far as I can see, this was moved to the 3.x release for clap? Either way, I'd like to pronounce interest in this feature. Not only for git-dit but also for imag.

[kbknapp]

@matthiasbeyer yes, this is a feature I want, but need to get 3.x out the door first because otherwise it'll just keep getting pushed off and pushed off.

[valpackett]

Since clap has plenty of information about the structure of commands and args and whatnot, it should be possible to build pages in the mdoc language, which is semantic (i.e. it has entities like "flags" and "commands" instead of just "bold text" etc.)

[Dzordzu]

Is there any way to generate json schema from the command?

[epage]

At this time, we do not. The issue for that is #918.

The clap-serde project could be a good place for this. See aobatact/clap-serde#11.

[tgross35]

For anyone like me who stumbles across this long issue but can't find the correct answer: the official crate is clap_mangen (it's not mentioned anywhere on this thread)