[SciPy-Dev] Warning of deprecation in doc's ?
Thu Jun 3 11:58:25 CDT 2010
On Thu, Jun 3, 2010 at 8:43 AM, Ralf Gommers
> On Thu, Jun 3, 2010 at 10:15 PM, <firstname.lastname@example.org> wrote:
>> On Thu, Jun 3, 2010 at 10:07 AM, Bruce Southey <email@example.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
>> documentation changes should be added to:
>> 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
> .. warning::
> `myfunc` is deprecated and will be removed in SciPy 0.9. Look at
> `thatfunc` for equivalent functionality.
> SciPy-Dev mailing list
More information about the SciPy-Dev