[SciPy-Dev] Warning of deprecation in doc's ?
Thu Jun 3 09:07:42 CDT 2010
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
> <firstname.lastname@example.org <mailto:email@example.com>> wrote:
> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis
> <firstname.lastname@example.org <mailto:email@example.com>> 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
> 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@scipy.org <mailto:SciPy-Dev@scipy.org>
> SciPy-Dev mailing list
Users should first check that numpy does not have the functionality that
a user needs. 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
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:
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev