Please write a man page for the poetry-dynamic-versioning CLI

[baldurmen]

Hello!

I maintain this Python library in Debian.

Would it be possible to write a man page for the poetry-dynamic-versioning CLI? We're pushing it to /usr/bin/poetry-dynamic-versioning, but, as for all binary executable, it would be best if it also had a man page.

FWIW, in the past I've enjoyed using rst2man for this task, as it's simple, easy to use and it's provided by Python docutils project.

Here is an example: https://github.com/whipper-team/whipper/tree/develop/man

Cheers,

[mtkennerly]

Hi! I don't mind setting something up here. Some questions:

• Naively, could you convert the README to a man page as part of your packaging process? I'm not too familiar with man page conventions, so maybe that's too far removed from how to use the CLI itself.
• In my Rust projects, I have a Markdown file with the raw --help output, like https://github.com/mtkennerly/ludusavi/blob/master/docs/cli.md . Could you convert something like that to a man page (probably easier with one file per command) as part of your packaging process?
• Would you need the document to be included in the wheel, or is it enough to have it in the repo?

[baldurmen]

* Naively, could you convert the README to a man page as part of your packaging process? I'm not too familiar with man page conventions, so maybe that's too far removed from how to use the CLI itself.

No, man pages have a specific format and the README would be too different. Some of the information in the README can definitely be copied to the man page though.

* In my Rust projects, I have a Markdown file with the raw `--help` output, like https://github.com/mtkennerly/ludusavi/blob/master/docs/cli.md . Could you convert something like that to a man page (probably easier with one file per command) as part of your packaging process?

That would be possible (there are projects like help2man that do this) but I would advise against it, as the man pages produced like this are typically not very good :(

* Would you need the document to be included in the wheel, or is it enough to have it in the repo?

We don't use the wheel for the Debian package at all, having the man page in the git repository would be ideal.

[mtkennerly]

I found argparse-manpage and tried setting it up; it hooks directly into the code rather than trying to parse the help text after the fact. Could you check it out and see if the output is good enough? (I've also added it for Dunamai - not sure if you're involved with its Debian package as well.)

• poetry-dynamic-versioning: https://github.com/mtkennerly/poetry-dynamic-versioning/blob/master/docs/poetry-dynamic-versioning.1
• Dunamai: https://github.com/mtkennerly/dunamai/blob/master/docs/dunamai.1

[mtkennerly]

@baldurmen I'll go ahead and close this, but let me know if you need me to adjust the man page further.