Man page generation

[Arcterus]

We need to decide what documentation system to use. I assume we want support for man pages, which means we can either roll our own generator (like in ripgrep, which, last I checked, first generates an AsciiDoc file in build.rs) or use something like Sphinx, which is used in uutils/coreutils.

[mssun]

I think the help generated by clap is pretty good for now, and probably it will support generating man page in the future (clap-rs/clap#552).

I think both ripgrep and uutils/coreutils are fine for me. Do you know the pros and cons for these two? The only thing is that it will introduce external dependencies for building.

Anyway, either way is OK for now. I prefer to leave this issue for later discussion. Maybe we should focus more on polishing the tools?

[Arcterus]

Sphinx supports generating documentation in a variety of formats, so we wouldn't be limited to man pages (and we could host the generated HTML automatically using Read the Docs). It's also pretty popular and used in several well-known projects (the Linux kernel being one of them). A disadvantage is we would most likely need to maintain the reStructuredText files separately from the actual utilities.

It might be easier to maintain the docs using the ripgrep approach (as we wouldn't need to maintain the docs separately from the utilities), but it's less flexible overall. I'm also not 100% sure what benefits AsciiDoc has over Sphinx/reStructuredText in terms of possible output formats/documentation hosting.

One thing worth considering as well is that the main AsciiDoc implementation is Asciidoctor, which is written in Ruby, whereas Sphinx is written in Python.

Also yes, clearly the tools themselves should come first. We'll need to figure this out relatively soon though to avoid falling hopelessly behind in terms of documentation.

[mssun]

clap is working on generating man page: clap-rs/clap_generate#1

But it just started, hopefully will be usable in months. Let's check it later.

[yoshuawuyts]

We (CLI-WG) released v0.1.0 of the man crate today. Perhaps it fits your needs? https://github.com/rust-clique/man

If it doesn't we'd love to hear from you so we can improve it further ✨

[mssun]

Great, thanks @yoshuawuyts.

If I understand correctly, the rust-clique/man crate is for write man pages manually. We are looking for automatically generating man pages from clap rules (if possible). For the rust-clique/main crate, we have to maintain man pages as well as clap implementations. But I'm not sure what else we may face in terms of auto generating man pages. @Arcterus, do you have any suggestion for this?

[yoshuawuyts]

@mssun fwiw I've tried generating man pages from clap 2 (structopt), and didn't manage to get all information I needed from it. That's why we focused on getting support for clap 3 instead. Maybe you'll be able to pull it off, but I figured it'd be useful to share regardless.

If I understand correctly, the rust-clique/man crate is for write man pages manually.

And yep, that's correct! 😁

[mssun]

Thank you. My concern is that there are tens of cli tools in our project, maintaining their man pages and args parser are painful. Do you think it's worth waiting for clap 3? Is there any estimated time for this feature in clap 3?

[yoshuawuyts]

Do you think it's worth waiting for clap 3? Is there any estimated time for this feature in clap 3?

I don't have an exact timeline, but I believe Clap 3 is being targeted for this fall/winter - with an alpha probably coming out before that.

[Arcterus]

IMO we should just wait until Clap 3 unless we want to write some sort of system that generates the Clap stuff and the man page stuff at the same time (so basically wrap both Clap and man). It looks to me like man is probably more suited for libraries that generate man pages as part of whatever they do (like Clap) rather than use by the end user directly.