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

[Pauli Virtanen]

Tue, 09 Dec 2008 07:48:04 +0200, Scott Sinclair wrote:
>> 2008/12/8 Tom Grydeland <tom.grydeland at gmail.com>: Just to get my hands
[clip]
>> 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".

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