[SciPy-Dev] Warning of deprecation in doc's ?

[Vincent Davis]

On Thu, Jun 3, 2010 at 8:07 AM, Bruce Southey <bsouthey at gmail.com> wrote:
> On 06/02/2010 10:28 PM, Benjamin Root wrote:
>
> As a power user of these tools, I often will encounter these warnings while
> bulding my code piece-wise, however, I can easily imagine a case where a
> regular user simply seeing a useful feature and spending time coding around
> it, only to discover that it will soon be deprecated.  I would certainly be
> annoyed in such a case.
>
> A quick and easy way to list deprecations would be towards the end of the
> docstring, but the user might not scroll all the way down past the feature
> that they found.  So, to raise visibility, such deprecation warnings should
> be towards the beginning of the docstring.
>
> Just a thought... is it feasible for the doc building system to scan through
> the function code and spot a deprecation warning and thereby be able to add
> a list of deprecation warnings to the docstring?  Obviously, such warnings
> would have to follow some standard format, but it would be neat if such
> things could be automated.
>
> Just my 2 cents,
> Ben Root
>
> On Wed, Jun 2, 2010 at 10:07 PM, David Goldsmith <d.l.goldsmith at gmail.com>
> wrote:
>>
>> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis <vincent at vincentdavis.net>
>> wrote:
>>>
>>> For example scipy.stats.stats.cov when you view source has
>>> "scipy.stats.cov is deprecated; please update your code to use
>>> numpy.cov." Should this be in the docs ? and is there an example of
>>> how this should be pointed out.
>>> This is something I actually implemented in a program then discovered
>>> that is was deprecated. I would have like that to be in the online
>>> docs.
>>>
>>> Thanks
>>> Vincent
>>
>> I vaguely recollect this being discussed before, but I can't find anything
>> about it in our docstring Standard, in our Q+A section, nor (easily) at the
>> Python site (generally, when in doubt, we default to Python docstring
>> standards); so, how 'bout it guys and gals: should deprecation be noted in
>> docstrings and if so, where and how?
>>
>> DG
>>
>>
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
> Users should first check that numpy does not have the functionality that a
> user needs.

This is news to me, My point is that unless this is a very clearly and
obviously presented in scipy it is an assumption only you know about
:)

Vincent


Duplicated functionality between numpy and scipy is or was a
> main reason for depreciation. There are or were cases where numpy is
> different than scipy but I think these are being corrected as when these are
> found.
>
> Many of the warnings predate the numpy and scipy documentation marathon
> efforts and some depreciations may still be in tickets so it is very
> doubtful that an automated system will detect either of these cases anyhow.
> In the doc marathon someone will have to find these cases and deal with them
> appropriately - noting, as the person who created the ticket, that some of
> the scipy.stats should be gone in the tentative scipy 0.9 release.
>
> In the future, someone will have to come up with a rule to force
> documentation change when a depreciation event occurs and then enforce it.
> In fact, for numpy (as scipy does not yet have the same policy) the desired
> documentation changes should be added to:
> http://projects.scipy.org/numpy/wiki/ApiDeprecation
>
>
> Bruce
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>