[Python-ideas] Enabling man page structure for python

[Mark Hackett]

In trying to reduce the repetition of option arguments to python scripts I 
basically needed to allow some structure to the program to be able to be 
automatically mangled so it could be used in

a) the getopt() call
b) the -h (give call usage) option in the program
c) Synopsis subheading in the man page
d) Options subheading in the man page

rather than having to keep all in synch just because someone wanted a "-j" 
option added.

Because it requires a programmed man page creation, Sphinx, pydoc et al 
haven't been really of any use, since they are YAML (Yet Another Markup 
Language) as far as I've been able to tell, not really able to allow runtime 
changes to reflect in document generation. I may have missed how, however...

So I used a dictionary and wrote a program to generate man pages based on that 
dictionary and included function calls to automate the four repetitions above 
into one structure, rather similar to what you need for ArgParse.

A dictionary allowed me to check the ordering, existence and allow optional 
and updatable sections to be used in man page writing. It also gave me a 
reason to use docstrings in public functions.

I know man pages are passe and GUIs generally don't bother at all, but it 
still seems to me that adding some core python utility to express a man page 
and allow programmatic use of the construction both to define the program and 
its description is still a large gap.

Making man pages easier to write would be enough, but I also think that if 
newcomers could see some utility in writing documentation inside the programs, 
they would do so more readily. And this learnt behaviour is useful elsewhere.

The attached program (if it appears!) is my solution, basically baby python. 
It still has one redundant repetition because getopt() does it that way. And 
it has some possibly silly but useful markup based on the basic python data 
types (e.g. it displays a list differently from a scalar string).

It is meant to illustrate what I felt was not possible with python as-is to 
see if there is a way to make this work done redundant.

There are a few other people out there who have had to roll-their-own answer 
to the same problems. They solved it slightly differently and didn't include an 
ability to enforce "good practice" in man page creation which I think is 
warranted.

So I do feel there is room for python to stop us flailing around trying to find 
our own solution.

Is there agreement from others?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: make_manpage.py
Type: text/x-python
Size: 13874 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20121025/e0d84c29/attachment.py>