classification
Title: argparse: add ability to create a man page
Type: enhancement Stage: needs patch
Components: Library (Lib) Versions: Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Daniel.Walsh, Ingo.Fischer, Oz.Tiram, adregner, andialbrecht, bethard, dmalcolm, eric.araujo, jwilk, rhettinger, sigi, tshepang
Priority: normal Keywords:

Created on 2012-02-23 21:15 by Daniel.Walsh, last changed 2014-06-13 22:02 by Oz.Tiram.

Files
File name Uploaded Description Edit
build_manpage.py Oz.Tiram, 2014-06-11 17:13 Add a command class to setuptools.setup
Messages (9)
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 (eric.araujo) * (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 (eric.araujo) * (Python committer) Date: 2012-02-24 04:51
Forgot the link to the blog post: https://andialbrecht.wordpress.com/2009/03/17/creating-a-man-page-with-distutils-and-optparse/
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 (eric.araujo) * (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 (eric.araujo) * (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
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
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.
History
Date User Action Args
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: + build_manpage.py
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:06eric.araujosetmessages: + msg154216
2012-02-25 08:40:39andialbrechtsetnosy: + andialbrecht
2012-02-25 06:05:33eric.araujosetmessages: + msg154189
stage: needs patch
2012-02-24 18:04:54tshepangsetnosy: + tshepang
2012-02-24 09:53:04bethardsetmessages: + msg154125
2012-02-24 04:51:23eric.araujosetmessages: + msg154113
2012-02-24 04:50:59eric.araujosettitle: argparser should create a man page for me. -> argparse: add ability to create a man page
nosy: + eric.araujo, bethard

messages: + msg154112

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