[SciPy-user] Docstring standards for NumPy and SciPy

Gary Ruben gruben at bigpond.net.au
Wed Jan 17 06:59:34 CST 2007

Edward Loper wrote:

> If you really think that's too line-noise-like, then you could set  
> the default role to be math, so `x=12` would render as math.  But  
> then you'd need to explicitly mark crossreferences, so I doubt that  
> would be a win overall.

I want to highlight the distinction between the class/method-level 
docstrings and modules which are simply a large docstring used to 
implement an example. If we are to follow this model, as FiPy does, then 
I don't think there will be much (any?) LaTeX math in the 
class/method-level docstrings. In fact, I'd argue against LaTeX in these 
docstrings and probably against using matplotlib in the examples in 
these docstrings. It will mostly (only?) be in the module-level 
docstrings, which won't be seen in such environments as ipython. I 
expect they'll only ever appear to users as full html pages or LaTeX 
pages. Ed suggests using docutils directly for these. In FiPy, graphical 
output such as graphs and bitmaps are generated by a plotting package 
and embedded back into the resulting LaTeX. We would like to be able to 
do this for both html and LaTeX. I don't know if docutils supports this.

> [Gary Ruben]
>> 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.
> If you can explicitly specify what you'd like included in the output,  
> and how you'd like it formatted, then I can give you an idea of how  
> hard that would be to produce.  You are right that, at the moment,  
> epydoc's output generators are not terribly customizable.  And the  
> latex output isn't as pretty as I'd like.  :)

I think "see also" cross references to other methods are also important.

I think we want a way to just generate the docstrings as html and LaTeX, 
with cross-references as navigational aids. No inheritance information. 
This is because SciPy is currently more of a library of functions 
grouped into modules and the inheritance information is not usually 
important. A user just wants to know what methods and variables/fields 
are available. The endo-generated API docs here:
demonstrate this approach, where the class hierarchy has been separated out.

Gary R.

More information about the SciPy-user mailing list