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

[David Goodger]

Greg Ward <gward@mems-exchange.org> wrote on 2001-08-21 11:40:
> 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...

There are only so many hours in the day! :-)

> > 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.

It's a good idea to keep compatibility with other applications of
docstrings, to a point. Past that point lies creeping featurism and
overcomplexity. Some would say we've passed that point already ;-).

> > 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.

This will turn "Instance attributes:" into a simple paragraph, and the
attributes themselves into a block quote containing a definition list.
Although this is probably sufficient for Oscar's purposes, it doesn't
do the data any descriptive justice.

> > 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.

This creates a field in what we call a "field list", like an RFC822
header field, where "Instance-attributes" is the field name and the
field body consists of a definition list. Descriptively better than
option #1. But it still doesn't extract the semantic information
embedded in the description of the types.

I'm not sure about Tony's reference to a "specialized plugin" for
fields. Although we have settled on a syntax for field lists, there
has yet to be a discussion about what field lists actually *do*, if
anything, other than describing a data structure. I'm wary of it, but
one (remote) possibility is for field lists to acquire functionality
similar to that of directives. This leads us to...

Another option: use a directive::

    class Animal (Thing):
        """An animal, ie. a thing with multiple legs and possibly fur.
  
        Instance attributes:

        .. oscar::
           num_legs : int
               the number of legs this animal has
           furry : boolean
               whether this animal is furry or not
  
        Outsiders should use 'get_num_legs()' and 'is_furry()'
        to access these attributes.
        """

The "oscar" directive is free to define the syntax of its contents and
do anything it likes with the results.

> 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?

The DPS_ is the Python Docstring Processing System, subject of PEPs
256 and 258. reST [1] is reStructuredText, a markup syntax and parser
component of the DPS, possibly one of many. In my biased opinion, it
reStructuredText seems to have more support than any other
proposal, and the best chance of success. Juergen Hermann of MoinMoin
fame has shown definite interest, as have others (in private
correspondence), and still more are guardedly interested (wait and
see).

.. _DPS: http://docstring.sourceforge.net

.. [1] A complete reference to reStructuredText can be found at
   http://structuredtext.sourceforge.net/spec/reStructuredText.txt,
   and Tony's QuickRef is located at
   http://structuredtext.sourceforge.net/docs/quickref.html.

The reStructuredText parser is almost complete, but the DPS itself is
still in its infancy. The DPS is a framework, providing a clean
separation of input markup, processing, and output format.

If you get on the bandwagon with Oscar, it will help push
reStructuredText toward becoming the exalted "One True Syntax", and
help push the DPS toward completion and eventual inclusion in the
standard library. So please do! And your input is welcome.

>   * 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.

See Frederic Giacometti's post "documenting Python constraints on
types" (specifically the "iPhrase" attachment: doc-conventions.html)
for another approach:

    http://mail.python.org/pipermail/doc-sig/2001-May/001840.html

>     If there's an existing standard, I'm willing to entertain the
>     notion of modifying my parser to accomodate it.

Glad to hear it. I don't know of an established "standard"; if any,
I'd have thought it would have been developed by the Types SIG.

>     If not, may I propose my syntax as part of the standard?

It would be easy enough to fit it in. As it is, the text after
"Instance attributes:" is a reStructuredText definition list. The
"type : NAME" (etc.) syntax listed in `Oscar's type system`_ is a bit
inadequate, since a simple colon is so often used in plain text.

.. _Oscar's type system:
   http://aspn.activestate.com/ASPN/Mail/Message/types-sig/751935/
   unknown1

In combination with an "oscar" directive the syntax wouldn't be a
problem, since the directive can parse its data using a special local
syntax. It may even be feasible to add an optional classifier to
definition list items::

    term [ ' : ' classifier ]
        definition

This would be enough to separate the Oscar 'type' from the classifier.
The classifier could be formatted distinctively, in italics or
otherwise.

Opinions?

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net