[SciPy-user] Docstring standards for NumPy and SciPy

Brian Granger ellisonbg.net at gmail.com
Thu Jan 11 09:58:47 CST 2007


While I am all for better docstrings, I feel that the current state of
docstring formats is similar to how array libraries were before NumPy:
fragmented.  I think that using an existing standard (I prefer ReST
that can be processed by epydoc) will go much further in encouraging
folks to contribute good docstrings.

Also, using a common standard opens the door for interesting
applications and usages of those docstrings.  For instance, IPython
gives a user access to docstrings using the foo? notation.  We already
have a AJAX/web based IPython GUI and it would be very nice if foo? in
that could convert the docstring to html and display that.  Using
ReST, that is easy - with everyone using their own favorite markup
language, it is not practical.

Because of this, and the reasons that Fernando listed (too much
cognitive load in tracking all the different markup languages already)
we are using epydoc+ReST in IPython from now forward.

I realize that the line noise of ReST is less readable in Terminal
based things, but I feel it is a nice compromise for the
capabilities/features that you get.

Cheers,

Brian


More information about the SciPy-user mailing list