[SciPy-user] Docstring standards for NumPy and SciPy
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.
More information about the SciPy-user