[SciPy-user] Docstring standards for NumPy and SciPy

Gary Ruben gruben at bigpond.net.au
Thu Jan 11 05:27:46 CST 2007


I'm not sure I can add much to this discussion, except that currently no 
tools seem to do exactly what I think we want with ReST anyway, so if 
we're going to rely on existing tools, ReST may not be all that useful. 
I think what is needed is to generate a simple reference section in the 
proposed LaTeX version of the document which contains one indexed entry 
per numpy/scipy function, probably with 'see also' cross-references, and 
also an html version of same. Currently epydoc generates far too much 
information (2371 pages worth when I ran it on the numpy source a few 
days ago) and seems unable to be easily modified to reduce its output. 
The other thing we want is to be able to generate examples from heavily 
marked-up example modules a'la what FiPy does. I don't think epydoc even 
allows that without modification. Having said that, I think I'd tend 
toward using ReST because it doesn't grate with me like it seems to with 
Travis.

Gary


More information about the SciPy-user mailing list