[Python-ideas] Enabling man page structure for python
mark.hackett at metoffice.gov.uk
Thu Oct 25 16:48:32 CEST 2012
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"
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
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...
Size: 13874 bytes
Desc: not available
More information about the Python-ideas