[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?

[Mike Graham]

On Thu, Oct 25, 2012 at 10:48 AM, Mark Hackett
<mark.h...@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
_______________________________________________
Python-ideas mailing list
Python...@python.org
http://mail.python.org/mailman/listinfo/python-ideas

[Mark Hackett]

On Thursday 25 Oct 2012, Mike Graham wrote:
> On Thu, Oct 25, 2012 at 10:48 AM, Mark Hackett
>
> <mark.h...@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.

[Serhiy Storchaka]

On 25.10.12 19:08, Mark Hackett wrote:
> But doesn't help encourage and self-write those man page sections.

Try help2man.

[Éric Araujo]

Hi,

See http://bugs.python.org/issue14102 “argparse: add ability to create a
man page”

Cheers

[Andi Albrecht]

Hi,

On Thu, Oct 25, 2012 at 7:25 PM, Éric Araujo <mer...@netwok.org> wrote:
> Hi,
>
> See http://bugs.python.org/issue14102 “argparse: add ability to create a
> man page”

I've started to work on this issue some time ago. The starting point
was a man page formatter based on optparse I wrote earlier. But I've
encountered some problems since the output order of argparse
formatters differ from what to expect on a man page. IIRC I saw the
need to do some changes to the way how argparse formatters work but
unfortunately got interrupted by other work.

IMO adding a argparse formatter would the probably the right way to
add man page support. There would even be no need to add this to
stdlib then.

Best regards,

Andi

[Mark Hackett]

I'd still like to see some of the functionality in the code I'd written to
solve my problem in the parser, if not too much trouble, Andi.

I.e. at least a way to push more things to the man page (to be inserted in the
page) so that you can add in more things (like external function calls).

It's not obvious to me whether argparse also gives you a synopsis (self-
written --help option).


Cheers.