[Doc-SIG] docstring grammar

[Tim Peters]

[David Ascher]
> The only question I suppose is whether one should require a keyword (Test:
> or other) to keep the top-level syntax trivial, or special-case the
> recognition of >>>-beginning paragraphs.
>
> I'm leaning for the former, as it can evolve to the latter if there is
> sufficient call for it from the user base, and I think it does keep the
> code simpler.  But I'm willing to be swayed.

Parsing is never trivial, although it can be made *easy*, and you're already
e.g. special-casing the snot out of the first line of the docstring (unless,
as someone else recently and regrettably <0.3 wink> suggested, you split
that into keyword-introduced "Signature:" and "Summary:" paragraphs).

You're going to have *some* way to spell "what follows is an unstructured
code block up until the next empty line or end-of-docstring".  You'll end up
recognizing that with a regexp, like

    r"^\s*Example:\s*"

The code support will consist almost entirely of changing the regexp to

    r"\s*(Example:|>>>)\s*"

Not trivial, but as easy as it could be and stay this side of trivial
<wink>.

Here's the start of a very long module docstring:

"""
Rat objects support exact, unbounded rational arithmetic.

Skip to MODULE SUMMARY at the end for the short story.

Rat objects also support rounding and formating methods sufficient
to emulate floating-point arithmetic in your choice of base, number
of significant digits, and rounding discipline.

>>> from Rational.Rat import Rat  # Rat constructor
>>> from Rational import Format   # used later
>>> print Rat() # no args gets 0
0

Construct a Rat from an int, long, float, or string representing a
rational or float:

>>> print Rat(5), Rat(5L), Rat(5.0), Rat("5"), Rat("50e-1")
5 5 5 5 5
>>>

Or you can pass two ints or longs, to construct their ratio.  The
denominator must be >= 1:

>>> print Rat(5, 1), Rat(1, 5), Rat("1/5"), Rat("10/1010_2")
5 1/5 1/5 1/5
>>>

The "_2" at the end of the last one there is a "base tag", and says
"10/1010" is to be interpreted as a ratio in binary notation.
Any int base >= 2 can be used.

etc etc etc
"""

There are dozens of example code blocks in this docstring.  Indenting them
all and tagging them with redundant "Example:" labels would be both ugly and
wasteful.

I *love* the thrust of the new proposals here because, frankly, I'm likely
never to run a docstring thru any sort of docstring processor (except
perhaps to extract the first line), and the current proposals have a nice
WYSIWYG flavor.  When a *Python* programmer sees ">>>", they know exactly
what they're about to get.

if-swaying-isn't-effective-next-it's-pouting-and-then-on-to-
    threats<wink>-ly y'rs  - tim