[Doc-SIG] Re: docstring signatures

[Edward D. Loper]

> PS.  Don't spend too much time trying to make StructuredText or some
> variation thereof work.  In my experience with systems that use ST
> (like ZWiki), it sucks.  There basically are two options I like:
> nicely laid out plain text, or a real markup language like Latex or
> DocBook.

Unfortunately, it's a bit late for that (there's been a lot of work
this month put into trying to get a ST variant to work).  I don't 
mind not using ST, but before we start working on other formatting
conventions, I thought I should get a better idea of what you would
or would not like, so we don't end up spending another month on
something you won't like. ;)

Here's the abstract from the PEP I've been putting together.  It
should give you a good idea of what we're trying to accomplish, at
least:

    Python documentation strings provide a convenient way of
    associating documentation with many types of Python objects.
    However, there are currently no widespread conventions for how the
    information in documentation strings should be formatted.  As a
    result, it is very difficult to write widely-applicable tools for
    processing documentation strings.  Such tools would be useful for
    a variety of tasks, such as:

        * Converting documentation to HTML, LaTeX, or other formats.
        * Browsing documentation within python.
        * Ensuring that documentation meets specific requirements.

    This PEP proposes that the Python community adopt a well-defined
    set of conventions for writing "formatted documentation strings."
    These conventions can then be relied upon when writing tools to
    process formatted documentation strings.

    Note that some Python programs may choose not to use formatted
    documentation strings.  For example, programs like Zope [1] have
    used documentation strings for purposes other than strict
    documentation, and it would be inappropriate to expect them to
    change how they use documentation strings.  Also, some programmers
    may prefer to write plaintext documentation strings.

Also, here are the "design goals" I defined:

    The following goals guided this PEP's design of conventions for
    writing formatted documentation strings.

        * Intuitiveness: The meaning of a well-formed formatted
          documentation string should be obvious to a reader, even if
          that reader is not familiar with the formatting conventions.

        * Ease of use: If the formatting conventions are to be
          accepted by the Python community, then it must be easy to
          write formatted documentation strings.

        * Formality: The formatting conventions must be formally
          specified.  A formal specification allows different tools to
          interpret formatted documentation strings consistantly, and
          allows for "competing, interoperable implementations," as
          specified in PEP 1 [5].  

        * Expressive Power: The formatting conventions must have
          enough expressive power to allow users to write the API
          documentation for any python object.

    The following "secondary design goals" follow directly from the
    primary design goals, but are important enough to deserve separate 
    mention:

        * Simplicity: The formatting conventions should be as simple
          as is practical, and there should be minimal interaction
          between different aspects of the formatting conventions.
          This goal derives from intuitiveness and ease of use.

        * Safety: No well-formed formatted documentation string should 
          result in unexpected formatting.  This goal derives from
          intuitiveness.

So the question then is what sort of markup language we should define.
I'd be quite happy to use something like Javadoc uses (but with a more
restricted set of acceptable XML elements), but other people think
that it's too hard to read/write...

I'm also curious why you don't like ST-like markups.  We've been
putting a fair amount of work into formalizing it & making sure it's
"safe" (e.g., it's an error to say *x**b*c**d*).  If we can
successfully do both, would that alleviate some of your concerns
about ST? 

Any info you can give on what you would like to see come out 
of this project (or pointers to info) would be most appreciated.

-Edward