[SciPy-dev] Scipy Tutorial (and updating it)

Pauli Virtanen pav@iki...
Tue Dec 9 03:04:37 CST 2008

Tue, 09 Dec 2008 07:48:04 +0200, Scott Sinclair wrote:
>> 2008/12/8 Tom Grydeland <tom.grydeland@gmail.com>: Just to get my hands
>> The first problem I ran into is that there is no way to tell the
>> documentation system that I am documenting a class instance, so the
>> "Parameters" and "Returns" sections are both mandatory, while only the
>> latter actually makes sense.  I see there is some specal handling of
>> class documentation, which might work for objects (instances) also,
>> perhaps with some modifications?
> The doc wiki might need to be changed to understand class documentation
> better.  No doubt Pauli can comment on this.  In the meantime, it is
> best to use the class documentation guidelines as closely as you can:
> http://projects.scipy.org/scipy/numpy/wiki/
> Have a look at the section "Documenting classes".

Note that `mgrid` is an object and not a class; class documentation is 
already handled. We don't have a standard for objects, so the parser 
assumes the format is the same as for functions.

>> Another problem is that the "See Also" entries are not showing up as
>> cross-references (or even as a dictionary list).  What did I miss?
> This looks like a bug, some cross-references aren't resolved. I suggest
> using one of the "See Also" formats shown here:
> http://projects.scipy.org/scipy/numpy/browser/trunk/doc/example.py#L37
> and making sure it is easy to read in plain text.  Once the
> cross-referencing issues are resolved, the docstring should just work.

The See Also section won't work if the whole docstring is not formatted 
per the standard. Could be fixed, yes.

Pauli Virtanen

More information about the Scipy-dev mailing list