[Tutor] how to write documentation for a script

[Jeff Shannon]

Paul Tremblay wrote:

>Is there a way to include documentation within the actual script, as you
>can in perl? The book I have on Pyton, called *Core Pyton,* states that
>you put the documentation between quotation marks right after the
>startup line:
>
>#!usr/bin/python
>
>" This script converts Microsoft RTF to XML.."
>
>However, this only allows for the simplest form of documentation. You
>can't bold words, make headers, and do other things that you can in
>perl.
>

I know nothing about how things work for Perl, but Python itself has no 
facilities for internal documentation to be anything other than plain 
text.  You can use docstrings for the module (like that example above) 
and for each function, class, method, etc, but they're all plain text.

You might, however, want to look into something that's called (IIRC) 
reStructured Text.  I *think* that ActiveState has their hands in this, 
but I'm not sure -- I remember some discussion of it, and even some 
attempt to encourage all Python modules to use it for docstrings, but 
that's about it.  (I'd imagine that Google would find it, or you could 
check the PEP listings on python.org.)  What I can say is that it's a 
plain-text markup scheme, whereby something can be easily readable as 
plain text but can also be parsed and re-presented in a fancy formatted 
way with appropriate tools.  By using rST, you'd be able to have 
readable docstrings in your modules, and then use a simple tool to 
extract that documentation and turn it into prettified HTML (or use 
Reportlab to crank out a PDF, or whatever...)

Jeff Shannon
Technician/Programmer
Credit International