[PYTHON DOC-SIG] Structured documentation syntax

[Ka-Ping Yee]

Hi -- i just saw the following on python-list:

> Daniel Larsson has released gendoc 0.6 for your documentation
> pleasure. The big change here is the adoption of structured text
> for the doc string formatting standard.

-- and went to have a look at the doc-sig page to find out
what the formatting syntax was.

Syntactic things:
-----------------

I know that it may not be my place to speak so soon, as i have
not spent any time researching what has been done, but a look
at the description on the doc-sig page produced these thoughts
(in order of decreasing strength):

  - Double-quotes seem too common to be used as hyperlink delimiters.
    More in keeping with common practice might be the use of [],
    the way most people use them to mark references.

  - Also, it would make sense for double and single quotes to both
    mark example code.  What if you need to talk about a single-quoted
    string, for example?

  - As noted on the page, use of "--" is reasonably common for
    em-dashes (in fact, i'd even suggest turning them into real
    &emdash; entities in HTML).  Why not use "::" instead for
    tagged list elements?

  - Couldn't you just choose one bullet marker for list elements,
    instead of three?

  - Is it true that a first-level list begins "12 First sentence..."
    but deeper levels begin "3.4. First sentence..."?  That is, the
    description on the page seems to imply that the periods follow
    each ordering component, rather than separate them.

  - It might be nicer (simpler) to use _underscores_ for italics
    and use *single asterisks* for bold.  (Special Python names
    that start and end with underscores should be marked as code
    examples anyway...)

Btw, how do you make headings?  Do you just make everything a
sub-paragraph of a short paragraph containing the heading?


Semantic things:
----------------

Has there been any thought towards a well-defined standard
for documenting functions?  I'm thinking of things about
the interface, like parameter lists and descriptions of
parameters, and maybe a defined place for a one-sentence
(or even one-predicate) summary of what the function does,
and/or what circumstances it expects to be run under.

I think this could be fairly useful.  A project i'm working
on now (called MINSE, for the representation of structured
expressions -- like math -- in HTML documents) needs a way
to describe just these kinds of things about functions, and
not just for the sake of documentation but actually as a real
part of its operation.  I want it to produce semantic information
attached to the structures in the expression, and the perfect
place to describe this seems to be __doc__.  So i am thinking
about designing a way to specify this information, but after
reading the post thought that it might be better for gendoc
and MINSE to understand things the same way.

For more info on MINSE, please see http://www.lfw.org/math/.
(Slightly out of date, so i can give more details if anyone
has questions.)

It currently has a working renderer for math expressions,
which makes it possible for anyone to write math directly
in their HTML and anyone to view it in any graphical OR
textual browser.  It's done in Python, of course. :)


Ping

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================