Title: argparse: add ability to create a man page
Type: enhancement Stage: needs patch
Components: Library (Lib) Versions: Python 3.6
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Aaron.Meurer, Daniel.Walsh, Ingo.Fischer, Oz.Tiram, acucci, adregner, andialbrecht, bethard, bignose, bochecha, dmalcolm, josh.r, jwilk, matthewjohn, merwok, paul.j3, rhettinger, sigi, tshepang, zbysz
Priority: normal Keywords:

Created on 2012-02-23 21:15 by Daniel.Walsh, last changed 2017-01-10 00:54 by paul.j3.

File name Uploaded Description Edit Oz.Tiram, 2014-06-11 17:13 Add a command class to setuptools.setup
Messages (12)
msg154090 - (view) Author: Daniel Walsh (Daniel.Walsh) Date: 2012-02-23 21:15
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.
msg154112 - (view) Author: Éric Araujo (merwok) * (Python committer) Date: 2012-02-24 04:50
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?
msg154113 - (view) Author: Éric Araujo (merwok) * (Python committer) Date: 2012-02-24 04:51
Forgot the link to the blog post:
msg154125 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-02-24 09:53
I think adding a new formatter for man pages would be generally useful. Assuming someone provides a patch. ;-)
msg154189 - (view) Author: Éric Araujo (merwok) * (Python committer) Date: 2012-02-25 06:05
Alright :)  I’ve contacted the author of the blog article to ask him if we can reuse his code.
msg154216 - (view) Author: Éric Araujo (merwok) * (Python committer) Date: 2012-02-25 08:57
Andi, the author of the blog post, will work on a patch.
msg220288 - (view) Author: Oz Tiram (Oz.Tiram) * Date: 2014-06-11 17:13

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 itself. My solution is an extension of Andial's brecht solution that uses ofcourse argparse.

You can see it in action in

I am also attaching the code here. 

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

msg220380 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-06-12 20:09
> I have been wanting this feature for quite a long time

Me too.
msg220506 - (view) Author: Oz Tiram (Oz.Tiram) * Date: 2014-06-13 22:02
@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.
msg244981 - (view) Author: Mathieu Bridon (bochecha) * Date: 2015-06-07 23:30
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.
msg261371 - (view) Author: Ben Finney (bignose) Date: 2016-03-08 19:45
Oz Tiram wrote:

> I doubt if the correct place for formatting a man page should be in 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’.
msg263855 - (view) Author: Alessandro Cucci (acucci) * Date: 2016-04-20 18:35
I would like to work on a patch if nobody currently are working on it. I'll keep you updated
Date User Action Args
2017-01-10 00:54:07paul.j3setnosy: + paul.j3
2017-01-07 14:28:27matthewjohnsetnosy: + matthewjohn
2016-04-20 18:35:46acuccisetnosy: + acucci
messages: + msg263855
2016-04-19 19:27:52zbyszsetnosy: + zbysz
2016-03-08 19:45:50bignosesetversions: + Python 3.6, - Python 2.7
2016-03-08 19:45:39bignosesetnosy: + bignose
messages: + msg261371
2015-06-07 23:30:42bochechasetmessages: + msg244981
2015-06-07 23:00:19bochechasetnosy: + bochecha
2014-10-14 08:38:55josh.rsetnosy: + josh.r
2014-10-13 18:23:04Aaron.Meurersetnosy: + Aaron.Meurer
2014-06-13 22:02:52Oz.Tiramsetmessages: + msg220506
2014-06-12 20:09:24rhettingersetnosy: + rhettinger
messages: + msg220380
2014-06-11 17:57:18guettlisetnosy: - guettli
2014-06-11 17:13:26Oz.Tiramsetfiles: +
versions: + Python 2.7, - Python 3.3
nosy: + Oz.Tiram

messages: + msg220288
2013-01-11 12:23:27guettlisetnosy: + guettli
2012-12-04 07:21:08sigisetnosy: + sigi
2012-06-12 18:41:36jwilksetnosy: + jwilk
2012-04-15 02:05:26adregnersetnosy: + adregner
2012-03-12 15:10:59Ingo.Fischersetnosy: + Ingo.Fischer
2012-02-25 08:57:06merwoksetmessages: + msg154216
2012-02-25 08:40:39andialbrechtsetnosy: + andialbrecht
2012-02-25 06:05:33merwoksetmessages: + msg154189
stage: needs patch
2012-02-24 18:04:54tshepangsetnosy: + tshepang
2012-02-24 09:53:04bethardsetmessages: + msg154125
2012-02-24 04:51:23merwoksetmessages: + msg154113
2012-02-24 04:50:59merwoksettitle: argparser should create a man page for me. -> argparse: add ability to create a man page
nosy: + merwok, bethard

messages: + msg154112

versions: + Python 3.3, - Python 2.7
components: + Library (Lib), - None
2012-02-23 21:15:59Daniel.Walshcreate