[Doc-SIG] Docstring grammar: a very revised proposal

[Mark Hammond]

[David writes back on Sat 22-Jan-00]

> In preparation of a discussion at IPC8's DevDay,

Well, I think we all agree on how that went ;-)

> and anticipating (perhaps mistakenly) some resistance to
> "yet another structured text format" from Jim Fulton, I

In the short discussion on that topic, it seemed that Jim had no great
objections.

So, as DevDay didnt achieve much, I think we should run with this grammar.

My comments, generally ignoring what Ken already commented on:

> StructuredText as XML without a DTD:

Im happy to ignore StructuredText for out-of-line doc for now.  The critical
issue we have to deal with is docstrings.  Did we ever determine what
OReilly's position on XML and particular DTDs is?

>     The requirement that a paragraph end with the word example or
>     examples or :: goes against my natural style, as I often do not

IMO, its not too bad, as it is only used to introduce single paragraph
code-block (if I read the rules correctly?)

>     If the two colons are not displayed by the renderer,
>     then my objection is diminished, although I would have preferred a
>     markup which is local to the paragraph which is affected

Agreed.

> Missing features:
>
>     The definition of references is well-designed for referencing
>     URLs.  The docstring proposal needs to address referencing other
>     code elements (methods of current class, other classes, other
>     methods of other classes, builtin modules, imported modules, etc.)
>     This is also more of a lack of feature than a real flaw, and
>     defining the namespaces for lookup of 'reference targets' would
>     probably go most of the way towards fixing the spec for our needs.

Definately agreed, and IMO quite a critical issue.

In the absense of any other complaints or comments about this proposal, I
suggest that this proposal is what we run with for doc-strings.  The key
problem is getting tools and code to work with this revised proposal, and
exactly what this means to StructuredText as used today by the Zope guys.

The key feature of this proposal is that it can already give us something to
work with.  As mentioned a few times on DevDay, we need a blessed doc-string
format so people can start writing docstrings in the knowledge tools will
follow.

So, does anyone else have any comments on David's proposal?  Can we work
towards a new set of "Structured Text for DocStrings" rules that people can
start using for their docstrings?

This SIG has been going for ages, and has been amazingly short on results (a
critisism that obviously includes myself!).  It really is time to get
something happening, and this is an excellent start!

Mark.