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

[David Goldsmith]

OK, we're getting enough proposed content here that I think a formal
modification of the docstring Standard is warranted; accordingly, I'm going
to file a ticket.  I'll post the link here and then if you want to be on the
notification-of-ticket-changes list you can go there and add yourself.  That
way, this discussion of where this entry should live, what it should
contain, how it should be formatted, etc., etc., will be in a more
appropriate, easier to find place.  Back shortly.

DG

On Thu, Jun 3, 2010 at 9:58 AM, Vincent Davis <vincent at vincentdavis.net>wrote:

> On Thu, Jun 3, 2010 at 8: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.
>
> 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?
>
> Vincent
>
> > .. 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 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100603/22647eb6/attachment.html>