Newbie can't figure out documentation practices

[Fernando Perez]

Antonios Christofides wrote:

> I don't understand how I am supposed to do this in Python. I know I can
> write documentation strings, but is there any command that can read them
> and format them into something like a man page or even plain text? I
> thought it would be pydoc, but it doesn't seem to work like perldoc. I'm
> almost concluding there's no standard way, and people are choosing
> whatever they like, e.g. pod, groff, DocBook, or LaTeX. No problem with
> that, I just want to make sure my conclusion is correct.

Unfortunately, that's one of the few true warts of python currently: no
automatic way of generating a manpage.  The usual idiom is to have a
top-level docstring and print that out if --help is passed on the command
line.  Docstrings are a fabulous _developer_ documentation system, but they
aren't so useful for user-level information.

Hopefully once reStructuredText becomes a more standard part of python's
culture, we'll be able to have a reasonably automatic way of producing man
output from some __manpage__ string or somesuch.  I guess it's just a
matter of adding a reST->nroff converter to docutils.

The only other area where you're likely to cry a bit is proper string
interpolation, which sucks in python.  Other than that, welcome to the most
amazing and enjoyable language to program I've ever used!

Best,

f.