argparse: add ability to create a man page

[DanielWalsh]

BPO	14102
Nosy	@rhettinger, @jwilk, @merwok, @davidmalcolm, @asmeurer, @bochecha, @serhiy-storchaka, @MojoVampire, @oz123, @alessandrocucci, @MatthewJohn, @mlouielu, @pablogsal, @asmeurer
PRs	bpo-14102: argparse: Add generate man page #1169
Files	build_manpage.py: Add a command class to setuptools.setup poc.py poc_2.py

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2012-02-23.21:15:59.985>
labels = ['type-feature', 'library']
title = 'argparse: add ability to create a man page'
updated_at = <Date 2018-06-15.11:04:11.134>
user = 'https://bugs.python.org/DanielWalsh'

bugs.python.org fields:

activity = <Date 2018-06-15.11:04:11.134>
actor = 'Pavel Raiskup'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2012-02-23.21:15:59.985>
creator = 'Daniel.Walsh'
dependencies = []
files = ['35576', '46809', '46812']
hgrepos = []
issue_num = 14102
keywords = []
message_count = 33.0
messages = ['154090', '154112', '154113', '154125', '154189', '154216', '220288', '220380', '220506', '244981', '261371', '263855', '291836', '291866', '291870', '291871', '291876', '291877', '291879', '291882', '291883', '319528', '319540', '319544', '319564', '319565', '319566', '319567', '319568', '319585', '319600', '319601', '319603']
nosy_count = 25.0
nosy_names = ['rhettinger', 'bethard', 'jwilk', 'eric.araujo', 'zbysz', 'dmalcolm', 'Aaron.Meurer', 'bignose', 'andialbrecht', 'bochecha', 'tshepang', 'paul.j3', 'sigi', 'Daniel.Walsh', 'serhiy.storchaka', 'Ingo.Fischer', 'adregner', 'josh.r', 'Oz.Tiram', 'acucci', 'matthewjohn', 'louielu', 'pablogsal', 'asmeurer', 'Pavel Raiskup']
pr_nums = ['1169']
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14102'
versions = ['Python 3.6']

[DanielWalsh]

I have developed a new tool virt-sandbox-service using argparse. Currently the argparse has the ability to print help and usage. Being naturally lazy, I think it should be able to print out a man page also. This would help with development and make maintaining the different documents.

[merwok]

Are you aware of help2man? It can transmogrify the output of “your-program-that-uses-argparse --help” to a man page. Another solution is to use docutils’ rst2man to convert some documentation file to the man format.

On the other hand, this blog post contains code implementing a custom optparse formatter for man pages, which could probably be adapted for argparse easily, so it does not look hard to implement. (Note that the code has no licensing information.)

Steven, what do you think? Too specialized for the stdlib or small, useful new feature?

[merwok]

Forgot the link to the blog post: https://andialbrecht.wordpress.com/2009/03/17/creating-a-man-page-with-distutils-and-optparse/

[bethard]

I think adding a new formatter for man pages would be generally useful. Assuming someone provides a patch. ;-)

[merwok]

Alright :) I’ve contacted the author of the blog article to ask him if we can reuse his code.

[merwok]

Andi, the author of the blog post, will work on a patch.

[oz123]

Hi,

I have been wanting this feature for quite a long time. IMHO, binaries and scripts should always include a man page. The Debian developers require that. However, man pages have a 'bizarre' format.
Long talk, short time. I did implement something. I tested it on Python 2.7 since my project currently only supports Python 2.7.
I think it should not be complicated to port to Python 3.X.

I doubt if the correct place for formatting a man page should be in argparse.py itself. My solution is an extension of Andial's brecht solution that uses ofcourse argparse.

You can see it in action in https://github.com/pwman3/pwman3

I am also attaching the code here.

I hope you will find this file useful. I would appreciate your comments too.

Regards,
Oz

[rhettinger]

I have been wanting this feature for quite a long time

Me too.

[oz123]

@Raymond Hettinger,
You don't have to wait anymore. I would be happy if you review the patch, and share your opinion.
I might have posted my patch too early. I am still doing changes on the upstream, in my github posted earlier.So, please test the one upstream.

[bochecha]

Any news on this?

The code posted by Oz Tiram (I took the latest from his github repo) works quite well, even with Python 3. (I just tested it)

It would be great if argparse could include the formatter class, as well as the distutils command.

[bignose]

Oz Tiram wrote:

I doubt if the correct place for formatting a man page should be in argparse.py itself. My solution is an extension of Andial's brecht solution

Thank you for that, Oz.

I see an easy seam to refactor this work into separate concerns.

The formatting of a man page from the parser for the command, can be coupled to the ‘argparse’ module since it is dependent only on an ArgumentParser plus some extra properties for populating the man page.

The building of one man page should not, IMO, be so tightly coupled to a Python distribution. There may be several different commands installed by one distribution. Each man page's fields should mostly come from the parser for the command, not from the distribution metadata. Instead, the build process should be told which parser to use for generating each of the man pages.

I propose to work on Oz's module and produce a man page formatter for exactly one ArgumentParser, as an enhancement for ‘argparse’.

[alessandrocucci]

I would like to work on a patch if nobody currently are working on it. I'll keep you updated