[SciPy-dev] Changes to trunk/scipy/optimize

[josef.pktd at gmail.com]

2010/2/9 Martin Lüthi <luethi at vaw.baug.ethz.ch>:
> Hi
>
> At Tue, 9 Feb 2010 03:05:41 -0800,
> Jarrod Millman wrote:
>> Now the question is where is the best place for us to reference
>> external, but relevant and useful Python projects.  My personal
>> feeling is that it shouldn't be in the 'see also' section of our
>> docstrings, but we don't have any official policy on that yet.  So we
>> need to have a general discussion about what the general policy should
>> be.
>
> I completely understand your reasoning. However, I would still find it useful
> if there were a docstring section named "similar packages", mentioning either of
>
> a) relevant packages that are closely painfully integrated with scipy and are
>   generally regarded as useful
>
> b) a link to the relevant URL of the topical software guide.
>
> Option (a) might lead to some "political" problems, which I cannot imagine
> being difficult. Option (b) would be useful in any case. While checking out
> code the Topical Software Pages or the Scipy Wiki are not the immediately
> obvious places to look for more relevant information.

I think this would be useful on the module or scipy subpackage level
but not for the docstrings for individual functions or classes. In my
opinion, the docstring of function should provide only closely related
functions and classes for quick lookup. Extra information should go
into a different section, for example in the statsmodels docs, I
included a page with related packages.

For the specific case of scipy.optimize, I think also some of the
internal See Also can be removed, since many of the docstrings are
almost a table of content of scipy.optimize, which also can be
directly seen on the subpackage level. If I remember correctly, in
some parts of scipy some weeding of umbrella SeeAlso has already
occured.

On Wiki versus documentation pages, I think it would be helpful to
introduce additional descriptive sections on the scipy.subpackage
level, which could include specific Topical Software.

I'm using the numpy/scipy docs mainly through htmlhelp (.chm) where
the tree view makes browsing very fast (similar to matlab help), maybe
the html pages need more links than this.

Josef


>
> Best, Martin
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>