[Doc-SIG] docstring grammar

[Mark Hammond]

> After a little thought, I'm tempted to remove the ::
> requirement as well.

I agree this would be a good thing.  I originally intended to reply in
context to all the good suggestions - however, I dont look like
finding time until after Christmas :-(

So here is my 2c worth, mainly echoing comments from others:

Drop the absolute requirement for the whitespace, especially with
bulleted lists.  People will generally not be editing these strings in
a word-processor, so will have control over the line breaks.

Thus:
* Any line starting with a word followed by a colon can be considered
a keyword.  If you dont want this, just make sure its not the first
word on the line.
* A star or dash starting a line can be considered a new list item.
Again, if it is truly a hyphen or whatever else, just adjust your line
wrap slightly so it is no longer the first word.

Other random thoughts:
* The [blah] notation is good, but needs to be well defined.  eg,
"[module.function]" when used in the context of a package should use
the same "module scoping" that Python itself uses.  However, the use
of brackets may conflict with people who use inline code (rather than
an example "block" - maybe something like "@" could be used?
@module.function@ would be reasonable.

* IMO, importing the module to extract this information is fine.  For
the 1% of cases where it is not and the author of the module needs to
use the tool, we could offer a hack - eg "sys.doc_building" will be
defined when the tool is running, so could fine tune their code
appropriately.  For the vast majority of cases, I guess that importing
would be just fine and make the tool simpler, thereby giving more
chance of it one day existing :-)  Indeed, do it the simple way, and
the first person who needs the parse-only option can help code it :-)

* Example/test code should be clearly identifiable.  Tim Peters
docstring tester could also be hacked to work with with format.
Further, it should be possible to have lots of discrete sample code,
each with their own discussion - eg:
"""
The following code shows how to do this:
Example:
  def foo():
    etc

/Example:
The following code shows how to do that:
Example:
  def bar():
    etc

As a final note:  The tool should be written with distinct "generate"
and "collate" phases, simply to resolve the cross-references.  It is
unreasonable to expect that all cross-references will be capable of
being resolved in a single pass.  Note sure exactly what this means
from an implementation POV, but it is important.

Thats about it.  I really like this, and feel it can is both powerful
and extensible enough to grow with us.  All we need now is the tool
:-)

Mark.