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

[Scott Sinclair]

Hi Tom,

> 2008/12/8 Tom Grydeland <tom.grydeland at gmail.com>:
> Just to get my hands dirty, I started on the `mgrid` and `ogrid`
> objects from numpy.lib.index_tricks (both of which I find very handy,
> and wish I had found earlier).  I am replicating text from the
> `nd_grid` class here.
>
> 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/CodingStyleGuidelines#docstring-standard

Have a look at the section "Documenting classes".

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

Cheers,
Scott