[PYTHON DOC-SIG] setext in doc strings
Robin Friedrich
friedric@rose.rsoc.rockwell.com
Tue, 13 Aug 1996 08:06:12 -0500
|> From owner-doc-sig@python.org Fri Aug 9 10:33 CDT 1996
|> Date: Tue, 06 Aug 1996 08:26:21 -0400
|> From: Jim Fulton <jim.fulton@digicool.com>
|>
|> Robin Friedrich wrote:
|> > .....
|> > Bummer. I didn't get it. Can you send it again? Be sure it's not >40K if
|> > you send it to a sig list - it won't get forwarded.
|>
|> Hm. It was only a K or so. I got a copy through the list. Dod anyone
|> else
|> not get the StructuredText note? Did everyone else get this note?
|>
|> Robin, I forwarded another copy to you.
Got it, finally. I've just recovered from a new IP number here so I'm
afraid I have missed much of last week's traffic. I've gotten your
StructuredText module (a couple days after you sent it) and have played
with it a little.
I have the following comments:
I would rather not have to separate each item in
a bulleted list by a blank line.
We need to incorporate a tagging method for hyperlink
URLs. Would the sextext method be acceptable for this?
I still don't see anything wrong with it.
Can we change the ** mapping to 'strong'? It seems
redundant with the * mapping.
Ordered list elements don't seem to work.
I can see some nice potential here for gendoc though and I'm sure Dan
can use pieces of it. When I said leverage off an existing setext idea
I meant that we could borrow from others that have paid some thought to
the same requirements we have with doc strings, not to adopt any
implementations verbatum. I think doc-sig should specify a nice doc
string format which serves our needs. The implementation in python
will be the easy part.
Below is an example of my doc string using the setext method...
class FramesetDocument(Document):
"""A minimal document suitable for entering Framesets.
Arguments are for contents **NOT** a document resource file.
No <body> markup. Instead add Frameset(s) with the constructor or
append method. Useful methods are _append_, _prepend_, _write_,
and _copy_. Others inherited from Document class are unused.
Keyword Parameters
------------------
title :: string to be used as the document title.
base :: object of the Base class
meta :: object of the Meta class
cgi :: if non zero will issue a mime type of text/html
"""
And following is what it might look like given the structured text support.
class FramesetDocument(Document):
"""A minimal document suitable for entering Framesets.
Arguments are for contents **NOT** a document resource file.
No <body> markup. Instead add Frameset(s) with the constructor or
append method. Useful methods are *append*, *prepend*, *write*,
and *copy*. Others inherited from Document class are unused.
Keyword Parameters
title -- string to be used as the document title.
base -- object of the Base class
meta -- object of the Meta class
cgi -- if non zero will issue a mime type of text/html
"""
Looks fine to me. What do others think?
-Robin
=================
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================