[Doc-SIG] docstring grammar

[Tim Peters]

[MarkH]
> * Example/test code should be clearly identifiable.  Tim Peters
> docstring tester could also be hacked to work with with format.

[DavidA]
> I need to go back and look at Tim's code again.

I already did <wink>.  Tim's code looks for:

   ^\s*>>>

and then sucks up everything following until the next all-whitespace line or
end of docstring (whichever comes first).

That is, I figured the contents of an interactive shell window didn't need
any markup beyond the leading PS1 Python already sticks there.  Given that
doctest.py is meant to be usable with near-zero effort, it wouldn't do to
require more markup than that.

Luckily, it almost fits your definition of a paragraph already.  It
shouldn't be any real effort to declare that ">>>" introduces a
structureless code paragraph extending until the next all-whitespace etc --
given that it's a format for Python docstrings, Python's own output deserves
some special treatment <wink>.

As to whether doctest should be fiddled to try to interpret some other form
of markup too, I don't think so.  The markup it inherits from the Python
shell is both sufficient and pleasant for its users.  Any other kind of
embedded sample code almost certainly isn't intended to be auto-verified, so
doctest *should* ignore it.

Nothing you're likely to do with docstrings is going to create problems for
doctest, so the only question is whether doctest's conventions create
problems for docstring markup.  I think they do now, but "shouldn't":
anyone pasting in an interactive session, whether for use with doctest or
for some other purpose, is going to want it treated as a code block.

full-speed-ahead-ly y'rs  - tim