PEP 287: reStructuredText Standard Docstring Format

[Quinn Dunkan]

On Wed, 03 Apr 2002 16:00:42 GMT, Terry Reedy <tejarex at yahoo.com> 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
>good
>> experience teaching stuctured text to my customers. After a very
>short
>> while they start to use it insted of html when generating content
>for
>> their sites due to ease of use.
>
>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 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.

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.

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