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?
On Thu, Oct 25, 2012 at 10:48 AM, Mark Hackett <mark.hackett@metoffice.gov.uk> wrote:
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
On Thursday 25 Oct 2012, Mike Graham wrote:
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.
Hi, See http://bugs.python.org/issue14102 “argparse: add ability to create a man page” Cheers
Hi, On Thu, Oct 25, 2012 at 7:25 PM, Éric Araujo <merwok@netwok.org> wrote:
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
On Friday 26 Oct 2012, Andi Albrecht wrote:
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.
On Thu, Oct 25, 2012 at 10:48 AM, Mark Hackett <mark.hackett@metoffice.gov.uk> wrote:
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
On Thursday 25 Oct 2012, Mike Graham wrote:
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.
Hi, See http://bugs.python.org/issue14102 “argparse: add ability to create a man page” Cheers
Hi, On Thu, Oct 25, 2012 at 7:25 PM, Éric Araujo <merwok@netwok.org> wrote:
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
On Friday 26 Oct 2012, Andi Albrecht wrote:
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.
participants (5)
-
Andi Albrecht -
Mark Hackett -
Mike Graham -
Serhiy Storchaka -
Éric Araujo