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

Vincent Davis vincent@vincentdavis....
Thu Jun 3 11:58:25 CDT 2010

On Thu, Jun 3, 2010 at 8:43 AM, Ralf Gommers
<ralf.gommers@googlemail.com> wrote:
> On Thu, Jun 3, 2010 at 10:15 PM, <josef.pktd@gmail.com> wrote:
>> On Thu, Jun 3, 2010 at 10:07 AM, Bruce Southey <bsouthey@gmail.com> wrote:
>> > On 06/02/2010 10:28 PM, Benjamin Root wrote:
>> >
>> > 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.
> There's enough docstring manipulation going on already I think, this is not
> that much work so manual would be better. It should be put in at the moment
> the deprecation takes place.
>> 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
>> I have never seen any guidelines or rules to add Deprecation Warnings
>> into the docstrings. It would be good to define a standard for the
>> docstrings first.
> It should be made as visible as possible in my opinion. A reST warning in
> between summary and extended summary would work. It should clearly state in
> which version it will be removed. Best to keep the text identical to the one
> passed to the deprecate decorator. A reason or alternative should be given
> as well.

I would prefer to see it at the very top.
If there is an easily available alternative why would I as a user not
what to immediately view that alternative?
If I am already using it then it is a good remider. Why put it after
the summary?


> .. warning::
>     `myfunc` is deprecated and will be removed in SciPy 0.9. Look at
> `thatfunc` for equivalent functionality.
> Cheers,
> Ralf
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev

More information about the SciPy-Dev mailing list