Equivalent of perl's Pod::Usage?

[Adam Funk]

I'm using to using Pod::Usage in my Perl programs (a snipped example
is shown below, if you're interested) to generate a little man page
when they are called with the -h option.

Is there an equivalent in Python?

Thanks,
Adam


##########

use Pod::Usage;

getopts("ha:b:c", \%option) ;

if ($option{h}) {
pod2usage(-verbose => 2);
die("\n\n");
}

# REST OF PROGRAM HERE!

#####
=head1 Documentation

=head2 Synopsis

COMMAND OPTION(S) [FILE(S)]

=head2 Options

=over

=item -h

Get this help.

....

=back

=cut
#####

 

[Dennis Lee Bieber]

I'm using to using Pod::Usage in my Perl programs (a snipped example
is shown below, if you're interested) to generate a little man page
when they are called with the -h option.

Is there an equivalent in Python?

I'd suggest you look in the Python references for docstring and/or
__doc__
--
Wulfraed Dennis Lee Bieber KD6MOG
(e-mail address removed) (e-mail address removed)
HTTP://wlfraed.home.netcom.com/
(Bestiaria Support Staff: (e-mail address removed))
HTTP://www.bestiaria.com/

 

[Neil Cerutti]

I'd suggest you look in the Python references for docstring and/or
__doc__

I found the example incomprehensible, so I looked it up in
perldoc. Anyhow, Python doesn't have it. Combining printing
various verboseness of usage messages with setting exit codes
with calling the exit function seems a little bizarre.

But I believe optparse will handle parsing arguments and printing
usage messages, though not, I think, setting verbosity levels and
exiting the program.

 

[Adam Funk]

I'd suggest you look in the Python references for docstring and/or
__doc__

Thanks.

 

[Adam Funk]

I found the example incomprehensible, so I looked it up in
perldoc.

Sorry about that! POD is a mark-up language that Perl's Pod::Usage
module can translate into man pages (and other documentation formats).

So what I'm really after is an easy way to generate something that
looks like a man page.

Anyhow, Python doesn't have it. Combining printing
various verboseness of usage messages with setting exit codes
with calling the exit function seems a little bizarre.

But I believe optparse will handle parsing arguments and printing
usage messages, though not, I think, setting verbosity levels and
exiting the program.

Thanks.

 

[Nick Craig-Wood]

Sorry about that! POD is a mark-up language that Perl's Pod::Usage
module can translate into man pages (and other documentation formats).

So what I'm really after is an easy way to generate something that
looks like a man page.

You might want to investigate reST

http://docutils.sourceforge.net/rst.html

That said, python does a good job of turning doc strings and class
descriptions into man pages even without any special markup, if you
wrote docstrings everywhere. Try pydoc on any bit of python (without
the .py) and you'll see what I mean

As for Pod::Usage - write the instructions for your script as a
docstring at the top of your file, then use this little function...

def usage(error):
"""
Print the usage, an error message, then exit with an error
"""
print >>sys.stderr, globals()['__doc__']
print >>sys.stderr, error
sys.exit(1)

 

[Ryan Ginstrom]

On Behalf Of Nick Craig-Wood

As for Pod::Usage - write the instructions for your script as
a docstring at the top of your file, then use this little function...

def usage(error):
"""
Print the usage, an error message, then exit with an error
"""
print >>sys.stderr, globals()['__doc__']
print >>sys.stderr, error
sys.exit(1)

argparse[1] also prints out very pretty usage for you.

[1] http://argparse.python-hosting.com/

Regards,
Ryan Ginstrom

 

[Adam Funk]

That said, python does a good job of turning doc strings and class
descriptions into man pages even without any special markup, if you
wrote docstrings everywhere. Try pydoc on any bit of python (without
the .py) and you'll see what I mean

As for Pod::Usage - write the instructions for your script as a
docstring at the top of your file, then use this little function...

def usage(error):
"""
Print the usage, an error message, then exit with an error
"""
print >>sys.stderr, globals()['__doc__']
print >>sys.stderr, error
sys.exit(1)

That looks useful; thanks.

 

[Paddy]

Thanks.

Adam, with doctest you can incorporate tests that show typical usage
into the documentation that are easy to keep up to date.
http://en.wikipedia.org/wiki/Doctest

- Paddy.