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

Skipper Seabold jsseabold@gmail....
Tue Feb 9 10:03:07 CST 2010


On Tue, Feb 9, 2010 at 9:31 AM,  <josef.pktd@gmail.com> wrote:
> 2010/2/9 Martin Lüthi <luethi@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.
>

>

+1 to (b).  While I think (a), would be of more use, it could be
difficult to keep such sections clean, short, and relevant, but having
them some other place that's readily accessible is a good compromise.

I've been hearing some very mild push back against using Python from
others recently, because it's a "dark horse."  Whether or not this is
a fair moniker is irrelevant, but I think part of this is because it
doesn't feel like a totally integrated environment for problem solving
across packages (the fact that Python is much more general than this
seems to get lost...).  The question then is, is scipy the place to
act as a gateway for scientific problem solving writ large?  I'd say
yes...

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

+1 Fair compromise.

> 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

Skipper


More information about the SciPy-Dev mailing list