[SciPy-Dev] Warning of deprecation in doc's ?
Thu Jun 3 09:14:55 CDT 2010
On Thu, Jun 3, 2010 at 8:07 AM, Bruce Southey <firstname.lastname@example.org> 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 <email@example.com>
>> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis <firstname.lastname@example.org>
>>> 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
>> 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?
>> SciPy-Dev mailing list
> SciPy-Dev mailing list
> 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
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
> 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:
> SciPy-Dev mailing list
More information about the SciPy-Dev