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

[Benjamin Root]

On Wed, Jun 2, 2010 at 11:05 PM, David Goldsmith <d.l.goldsmith at gmail.com>wrote:

> 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." :-)
>
> I will look into that tomorrow.  And I certainly agree that we should not
wait until pydocweb presents us a solution.  We should certainly follow some
sort of standard way to mark/tag/denote these deprecation warnings, that way
'grep' can still be a very valuable tool here.

Ben Root



> 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)
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100602/05e6f2c5/attachment.html>