From: Alan G Isaac <aisaac@am...> - 2007-01-11 14:09:03
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
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:
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.