PEP 287: reStructuredText Standard Docstring Format

Max M maxm at mxm.dk
Fri Apr 5 02:36:12 EST 2002


Terry Reedy wrote:

> "Max M" <maxm at mxm.dk> wrote in message news:3CAAC1FB.2050105 at mxm.dk...
>>Through Zope I have used Structured text extensively. Also I have

> Just curious: are you willing to (consider, at least) switching to
> ReST, or are we going to end up with two similar standards used by
> different parts of the Python community?  IE, do Goodger's arguments
> about why the differences from ST are improvements cut any ice with
> you?

What I don't understand here is that it seems that people considers 
structured text to be difficult. It really isn't. Any programmer can 
learn the basics in 15 minutes or less.

And it really is very very easy to write documents in it. I do belive 
that if I where ever to write a book (again) i would write it in ReST.

It find it rather ridiculous to use the JavaDoc approach with using 
markup in the docs, as it offers allmost nothing practial that ReST 
dosn't for solving this particular problem.

And as far as I can tell from the specs, ReST solves most of the 
problems I have had with structured text. A few things gets a little 
more complicated and some get simpler. All in all a good bargain.

I would certainly use it. I also hope that it gets integrated into Zope.

regards Max M


########################################
# 'old' structured text
########################################

This is an example of a headline in structured text

     Here is a paragraph.

     This is a second paragraph with a link to 
"http://www.python.org":http://www.python.org

     Here follows a piece of Python code::

         for i in range(10):
             print 'hello world'

     That is really all there is to it.

     Unless you want to use this paragraph headline

         That subcedes this paragraph




########################################
# ReST
########################################

This is an example of a headline in structured text
===================================================

Here is a paragraph.

This is a second paragraph with a link to http://www.python.org

Here follows a piece of Python code::

     for i in range(10):
         print 'hello world'

That is really all there is to it.

Unless you want to use this paragraph headline
----------------------------------------------

That subcedes this paragraph



########################################




More information about the Python-list mailing list