Sorry but personally I like the current approach of generating man pages from the .asciidoc templates. I think that argparse help and man pages are not the same thing (or does not need to be - man pages might contain more information). If there is something missing in the man pages, it's a bug and should be fixed but checking that man pages are complete seems to be a bit of overkill.

But if you think, this is a better approach, you can convert our man pages into automatically generated ones and send PR. If there is not anything or almost anything missing, then perhaps we could adopt that. I still don't think it will save us any work (because the automatic generation probably will not be perfect and we might then spend some time to try to tweak it for our purpose) but if you want, you can give it a try.

Generally, for a new project I would probably use the automatic generation but for existing project with already existing manually written man pages, this does not seem to be appropriate.

@clime wrote:

but if you want, you can give it a try.

Ok, I could (some day) try to revamp #141, but I guess there will be faster hands than mine.. :-)

I think that argparse help and man pages are not the same thing

I don't see this that easy :/. In many cases, the man program is not available, or the manual page is not installed (no-docs dnf configuration in docker), etc. The --help output is designed to have similar "powers" of manual page (so basically, the --help output should be self-standing alternative to man). Of course, longer documentation should belong to different medium, but....

To me, if there's something useful in manual page and not in --help, then there's a bug in --help output :-/ and we should guard against this, somehow (so it is imo worth having this issue at least open)

Generally, for a new project I would probably use the automatic generation but for existing project with already existing manually written man pages

Ack, new man pages could be generated then I guess.

We should decide here whether we want to keep the current solution (ascii doc templates) or do what @praiskup suggests. The ideal solution would be to generate part of man pages (commands and description) from argparse data but append to it some custom content (like EXAMPLES, authors, etc.), that would be written in asciidoc.

@praiskup: could you e.g. write an ascii doc macro that would generate argparse help?

If there is no way to combine those two sources (custom text in asciidoc/rst + argparse help) then I would prefer just stick to what we have and close this.

Related bugzilla: Bug 1494398 - Incomplete man page of the copr-cli: https://bugzilla.redhat.com/show_bug.cgi?id=1494398

FWIW, I already packaged argparse-manpage for fedora.

Ah sorry, I missed there was a question addressed to me.

@praiskup: could you e.g. write an ascii doc macro that would generate
argparse help?

I'm not sure I can help here, seems like too much work. Could we rather write
the help in plain text instead (directly into argparse object)?

If there is no way to combine those two sources (custom text in asciidoc/rst
+ argparse help) then I would prefer just stick to what we have and close
this.

I wouldn't probably insist on asciidoc input, but feel free to close -- np with
me, but then we never fix the desync of manpage and --help output.

Ah sorry, I missed there was a question addressed to me.

@praiskup: could you e.g. write an ascii doc macro that would generate
argparse help?

I'm not sure I can help here, seems like too much work. Could we rather write
the help in plain text instead (directly into argparse object)?

I think there is a solution here: http://www.methods.co.nz/asciidoc/userguide.html#_executable_system_macros. I don't think it should be particularly hard to implement...

This issue has been migrated to GitHub: https://github.com/fedora-copr/copr/issues/176