[Python-ideas] Enabling man page structure for python
mark.hackett at metoffice.gov.uk
Thu Oct 25 18:08:14 CEST 2012
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.
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.
More information about the Python-ideas