Re: Changes to trunk/scipy/optimize

On Tue, Feb 9, 2010 at 08:31,  <josef.pktd <at> gmail.com> wrote:
> 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.

+1

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

+1

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

+0.5

--

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco
_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev