[Doc-SIG] Re: docstring signatures
Edward D. Loper
Sat, 24 Mar 2001 15:07:38 EST
> 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
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
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  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 .
* 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
* 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
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
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.