[Tutor] how to write documentation for a script

[Abel Daniel]

Paul Tremblay (phthenry@earthlink.net) wrote:
> I have written a script that converts RTF to XML. The script is in perl,
> and I wish to convert it to Python. 
> 
> 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:
You can (or rather should) do similarly for documenting classes and
strings. See pep no.257 http://python.org/peps/pep-0257.html
> 
> #!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'm not complaining. I just want to make sure that I'm not missing
> something. I would like my script to have really nice documentation.
I guess the idea is that fancy markup isn't usefull if you edit the code
in a simple text-editor, or when experimenting at the interactive
prompt, as such tools cant handle anything more fancy than simple text.

So markup is only usefull if you process the code to generate
documentation. One such system is http://docutils.sourceforge.net/
"The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX."

I didnt try that, but it looks to be using reStructuredText, which
can do basic markup.


abli
abli@freemail.hu