[Tutor] how to write documentation for a script

[Magnus Lycka]

At Mon, 10 Feb 2003 14:51:55 -0500, 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:

Normally, you'd use ''' or """ so that you can embed line
feeds in the string. You can put these doc-strings in the
beginning of a module, a class or a function/method.

What you ask for, a standard for formatting of Python source
code documentatin, and tools to extract it, is still a new
thing in python, and not yet quite established.

There are two things you should look at. PyDoc and DocUtils.

The pydoc module and utility is included in Python.

If you type

 >>> import pydoc
 >>> help(pydoc)

you will use pydoc to look at itself...

In Windows C:\Python22\Tools\scripts\pydocgui.pyw will
start up a web based browser for inspecting python
modules, including documentation. I guess it's just
another path and .py instead of .pyw in other operating
systems. This is a great help to inspect python modules,
but it's not really what you look for.

As far as I understand, StructuredText has be replaced
by reStructuredText (rST). I think support for rST will
appear in 2.3, but I'm not sure. It certainly exists
though, and can be found in the Docutils web
http://docutils.sourceforge.net/index.html

See the PEPs http://docutils.sourceforge.net/spec/pep-0256.html
and http://docutils.sourceforge.net/spec/pep-0287.html

The PEPs are written in rST by the way. Another example
of rST use is the python-dev summaries, see
http://www.python.org/dev/summary/ where you can see them
translated to HTML.

For instance, view thew latest summary in HTML and rST:
http://www.python.org/dev/summary/2003-01-16_2003-01-31.html
http://www.python.org/dev/summary/2003-01-16_2003-01-31.txt

I assume pydoc will grok rST in time, but I don't think it
does today.

An example of a module documented with rST can be found here
http://docutils.sourceforge.net/docutils/statemachine.py


-- 
Magnus Lycka, Thinkware AB
Alvans vag 99, SE-907 50 UMEA, SWEDEN
phone: int+46 70 582 80 65, fax: int+46 70 612 80 65
http://www.thinkware.se/  mailto:magnus@thinkware.se