Home
Reading
Searching
Subscribe
Sponsors
Statistics
Posting
Contact
Spam
Lists
Links
About
Hosting
Filtering
Features Download
Marketing
Archives
FAQ
Blog
 
Gmane
From: Alan G Isaac <aisaac <at> american.edu>
Subject: SciPy documentation
Newsgroups: gmane.text.docutils.user
Date: Thursday 11th January 2007 14:12:07 UTC (over 11 years ago)
A discussion going on in the SciPy users forum
may interest reST developers and possibly some
users (those interested in code documentation).

The SciPy project is choosing a documentation
standard, and one proposal is reST as supported
by epydoc.

I am sure any comments about misconceptions or
easily overcome limitations will be very welcome.
The thread is titled Docstring Standards for
NumPy and SciPy, and can be seen here:
http://projects.scipy.org/pipermail/scipy-user/2007-January/subject.html

I will comment that the idea of using reST has
been received pretty well, although you will see
some reservations in the thread.  One concern is
that LaTeX math support remains in the sandbox but
is definitely needed for algorithm discussion.
Another concern was that reST table support is limited
(in particular, items cannot occupy mulitple cells).
I think this is right in the abstract; I am not persuaded
it will prove important in practice in this particular
application.  I know David was thinking about reST
support for code documentation in the past, so if those
thought have matured, this conversation might offer a good 
time and place to share them.

On another note, several people have expressed
concerns that it looks to be too hard to modify epydoc to
add new consolidated fields and to control the final output
(e.g., if just examples are desired).  I have no clue
whether or not this concern is well founded.  If anyone
can contribute insights, that would be valuable.

Cheers,
Alan Isaac



-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share
your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
 
CD: 3ms