[Python-ideas] Enabling man page structure for python

[Mark Hackett]

On Thursday 25 Oct 2012, Mike Graham wrote:
> On Thu, Oct 25, 2012 at 10:48 AM, Mark Hackett
> 
> <mark.hackett at metoffice.gov.uk> wrote:
> > 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...
> 
> Use sphinx.builders.manpage.ManualPageBuilder to make a manpage with
> sphinx. I wouldn't be shocked if other documentation systems had
> something similar.
> 
> I wouldn't be opposed to having argparse have some builtin or
> third-party capability for generating manpages. I wouldn't use getopt
> myself for anything but mimicing old, established, getopt-based
> interfaces. argparse has a lot more functionality already and it's
> more reasonable to expand it since it's a Python thing, not a
> pre-established thing.
> 
> Mike
> 

Sphinx allows better formatting control and then translation to troff macros. 
But doesn't help encourage and self-write those man page sections. Certainly 
much of the code would be rendered obsolete by using Sphinx calls, but the 
production of the man page and reduction of duplication won't happen.

For future inclusion, if it were to be included, argparse's method would be 
usable for defining the options. I don't know argparse benefits from having 
information about man pages in it, however, so a utility/class/method/include 
that can operate on what argparse requires to do the writing of the section(s) 
is entirely sensible. This may push argparse to include items that aren't used 
in itself, solely for documentation purposes.

If some methodology for solving this duplication with man page content were 
put in future python releases, that same methodology could be written into 
home-built code by those who have not yet access to the latest python at their 
work, with at least the sop to their efforts that nobody using their suite will 
have to relearn another way of doing it.

e.g. turning the argparse arguments into a getopt() call is pretty trivial if 
you don't have access to the argparse method.