[Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG

[Greg Ward]

On 21 August 2001, Tony J Ibbs (Tibs) said:
> I don't know if people here watch the Types-SIG, and I suspect that Greg
> doesn't watch the Doc-SIG, so...

I used to watch the doc-sig, but got overwhelmed.  Sorry...

> Thought for us - this is something we need to bear in mind, since it
> would be nice if we didn't muck up its appearance when processing a
> docstring for presentation.
> 
> Thoughts for Greg - currently the ``Instance attributes`` clause, as
> presented, would not be acceptable to the DPS/reStructuredText system.
> However, it's very near. There are two ways to change it to *make* it
> acceptable:
> 
> 1. Simply add a blank line after ``Instance attributes:``
>    (that would make the stuff thereafter a descriptive
>    list, which sort-of makes sense)

I'm pretty sure you can already do that with my current docstring parser.

> 2. Prepend an additional colon before ``Instance
>    attributes:``, and make the "title" into a single
>    "word" - for instance::
> 
>        :Instance-attributes:
> 
>    or::
> 
>        :InstanceAttributes:
> 
>    This looks a bit uglier, but means that the text
>    following could be handed to a specialised plugin
>    which knows to do special things with it.

I'm not opposed to generalizing the parser a bit to handle these forms.
Right now it just does this:
   if line.startswith("Instance attributes:"):

Looks like I could accomodate you by changing this to:
   if re.match(r':?instance[\ \-]?attributes:', line):
which doesn't bother me.

Question for the doc-sig:
  * is DPS/reST the One True Docstring syntax? do we have it at last?
    an end to the docstring wars?  or is this just one more proposed
    syntax?
  * do you have a standard for documenting instance attributes and
    their types yet?  I had to invent my own for Oscar, and I'm
    quite happy with it.  If there's an existing standard, I'm
    willing to entertain the notion of modifying my parser to
    accomodate it.  If not, may I propose my syntax as part
    of the standard?

        Greg
-- 
Greg Ward - software developer                gward@mems-exchange.org
MEMS Exchange                            http://www.mems-exchange.org