[Numpy-discussion] MoinMoin <-> docstrings gateway

Gael Varoquaux gael.varoquaux@normalesup....
Sun May 11 09:22:31 CDT 2008


On Mon, May 05, 2008 at 08:19:10PM -0400, dieter h wrote:
> I humbly suggest Sphinx[1] as the generating tool and markup rather
> than just regular ReST. I'm in the process of converting all of my
> local documentation to this engine's format.

I agree with you that Sphinx rocks hard. Ipython, sympy and Mayavi are
now using it, and it makes great docs. However I would absolutely avoid
using in docstrings something that is not pure ReST. There are many
applications, formatters, and wiki engine, web-apps, ... that can render
ReST. You are making your life much easier if you are sticking with ReST.

For your interest, with Mayavi, we have the docstrings in ReST, and are
generating a Sphinx document using them.

My 2 cents,

Gaël


More information about the Numpy-discussion mailing list