PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Fri, 5 Apr 2002 07:29, Quinn Dunkan wrote:
> On Wed, 03 Apr 2002 16:00:42 GMT, Terry Reedy <tejarex at yahoo.com> wrote:
> >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?
>
> I'm not speaking for Max, but my answer is "no."

I'm all for it, and I hope the ZC guys are too. If they don't I'll just have 
to write my own Zope product that wraps the ReST implementation. It's just 
too much of an improvement over the StructuredTexTNG implementation to ignore.


> I agree with Goodger that a convention for docstrings would be nice, and
> that structured text is the most reasonable candidate, but I don't agree
> that we need a complicated extensible format for it.  I use paragraphs,
> lists, verbatim code, and internal links (in the format I use, verbatim
> code goes in ''s and if it happens to be the name of a documented symbol in
> the current module it gets replaced with a link to the docs, so actually
> the format doesn't support links at all, but the translator can insert
> them), and anything with many more features, even if I personally don't use
> them, is likely to go over my "too complicated" threshold.

I've written a "primer" for ReST, which covers the exact simple components 
you describe above. At the moment, it's only available on my website:

   http://mechanicalcat.net/tech/quickstart.html

I hope that the primer clears up some of this confusion about the format 
being too complicated.


> A quick look at the python stdlib docs reveals that they could do just fine
> with the above features, except the use of footnotes, which I'm happy
> without.

I agree - I personally will be using ReST only for module-level docstrings, 
where they'll excell (since most module-level docstrings do tend to be 
verbose enough to warrant it :)


> Why not take Bobo's StructuredText and simplify it to the essentials rather
> than generalizing it to "the ultimate extensible structured text format"?

The problem with "Bobo's StructuredText" (wow, someone else who remembers 
Bobo :) is that it was never fully desgined, just implemented and hacked on 
over time. The beauty of ReST is that it's been designed from the start, and 
that means that if you want to ignore half of its features, you can. There's 
almost no chance of there being an accidental use of a feature you had no 
knowledge of, or inclination to use.




      Richard