[SciPy-user] Docstring standards for NumPy and SciPy

Edward Loper edloper at gradient.cis.upenn.edu
Wed Jan 17 11:20:04 CST 2007


[Gary Ruben]
> 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.

Yes and no.  Docutils has support for defining custom directives,  
which can do pretty much anything.  For example, epydoc defines a  
custom directive "..digraph::" which can be used to render directive  
graphs, defined using the graphviz dot language [1].  And it also  
defines some more specialized directives like "..classtree::".  So it  
would certainly be possible to add a "..plot::" directive, or  
something like that.  But those directives are not currently part of  
the official docutils distribution -- they're something you'd need to  
add on.  (But adding them on isn't too complex.)

[1] http://www.graphviz.org/

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

To create an inline hyperlink to another method with rst, you just  
mention it and put backticks around it.  E.g., something like "This  
is similar to `frobble()`, but a little bit tastier."  You can also  
have an explicit see-also section using ":see: `frobble`"

> 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.

Epydoc doesn't currently offer any way to supress inheritance  
information, but it looks to me (from cursory browsing) like the  
"endo-generated API docs" are structured in a somewhat similar way to  
the way that epydoc would do it.

-Edward



More information about the SciPy-user mailing list