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

[josef.pktd at gmail.com]

On Thu, Jun 3, 2010 at 10:43 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Thu, Jun 3, 2010 at 10:15 PM, <josef.pktd at gmail.com> wrote:
>>
>> On Thu, Jun 3, 2010 at 10:07 AM, Bruce Southey <bsouthey at 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.
>
> .. warning::
>     `myfunc` is deprecated and will be removed in SciPy 0.9. Look at
> `thatfunc` for equivalent functionality.

Sounds good to me,

Does Sphinx and the webeditor accept warnings at that location?

Josef

>
> Cheers,
> Ralf
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>