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

Ralf Gommers ralf.gommers@googlemail....
Thu Jun 3 09:43:02 CDT 2010

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100603/f2d434d8/attachment.html 

More information about the SciPy-Dev mailing list