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

[David Goldsmith]

On Wed, Jun 2, 2010 at 8:28 PM, Benjamin Root <ben.root at ou.edu> 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
>

pydocweb (our doc editing Wiki) does do something like that in that it
automatically prepends the function signature to the docstring (at least I
think it's pydocweb that's doing it), so I think it's possible in
principle.  code.google.com/p/pydocweb hosts a ticketing system (the
"Issues" tab) - may I ask you to go there and file an "enhancement" ticket
for this - the worst that can happen is that someone (probably Pauli V.)
will mark it as "will not do" with some sort of explanation as to why.

That said, pydocweb has a long backlog of open issues, and this is not the
highest priority among them.  Accordingly, we probably shouldn't wait for it
to solve our problem, i.e., we should still decide on where and how to note
this, and do it manually when we encounter the situation.  So, so far we
have one "vote" for "yes, near the beginning." :-)

DG



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


-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100602/c806b7c4/attachment.html>