[Tutor] how to write documentation for a script

Paul Tremblay phthenry@earthlink.net
Mon Feb 10 19:30:05 2003


On Mon, Feb 10, 2003 at 02:37:39PM -0800, Danny Yoo wrote:
> 
> 
> > >Is there a way to include documentation within the actual script, as
> > >you can in perl?
> >
> > You might, however, want to look into something that's called (IIRC)
> > reStructured Text.  I *think* that ActiveState has their hands in this,
> 
> 
> There's an explanation on the emerging "StructuredText" format here:
> 
>      http://www.python.org/sigs/doc-sig/stext.html
> 
> It looks like there is pretty good consensus for the StructuredText
> approach --- it allows us to combine some kind of markup (emphasis,
> paragraphs) within docstrings.
> 
> 
> And StructuredText seems pretty versatile; the Zope Book is written in
> StructuredText:
> 
>     http://www.zope.org/DocProjects/zope_book_signups/index_html
> 
> 

Thanks. Structured text looks like a good idea. However, I have spent
the last two hours (gRRRR) trying to get the pytondoc utility to work. 

I am given all sorts of warning errors. Here is the last one I got. My
thinking is that the module is too old to work with newer versions of
python?

Anyone had any success with this?

Thanks

Paul

error messages:


 DeprecationWarning: the regex module is deprecated; please use the re module
  import regex, regsub
/usr/local/lib/python2.1/regsub.py:15: DeprecationWarning: the regsub module is deprecated; please use re.sub()
  DeprecationWarning)
Error: Couldn't import StructuredText (exceptions.ImportError: No module named ts_regex)


-- 

************************
*Paul Tremblay         *
*phthenry@earthlink.net*
************************