[SciPy-Dev] Warning of deprecation in doc's ?
Thu Jun 3 13:18:05 CDT 2010
"Presently, the docstring standard does not specify how to note that an
object is to be deprecated; it has been proposed that this needs to be
"Obviously, this should be an optional section in general, but required for
objects once it is decided that they are to be deprecated.
"Discussion on scipy-dev agreed that this section should be at or near the
top, but at the top or between the One-line and Extended Summaries have both
been proposed - we will try to reach a consensus [in the ticket comments].
"Proposed format is to utilize Sphinx' .. deprecated:: directive; someone
please provide a concrete example of what this looks like (for example, does
this directive support multi-line content, and if so, what does that look
"Proposed content: summaries of deprecation schedule (in version number
time, not real time) and justification for deprecation (e.g., being
replaced, duplicates extant functionality elsewhere); existing alternatives
to obtain the same functionality. (Feel strongly that it should contain
something else? Add it below as a comment.)
"IMO, we should try to decide on this and update the standard by June 15 at
"Have I forgotten anything"
On Thu, Jun 3, 2010 at 10:49 AM, David Goldsmith <firstname.lastname@example.org>wrote:
> 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.
> On Thu, Jun 3, 2010 at 9:58 AM, Vincent Davis <email@example.com>wrote:
>> On Thu, Jun 3, 2010 at 8:43 AM, Ralf Gommers
>> <firstname.lastname@example.org> wrote:
>> > On Thu, Jun 3, 2010 at 10:15 PM, <email@example.com> wrote:
>> >> On Thu, Jun 3, 2010 at 10:07 AM, Bruce Southey <firstname.lastname@example.org>
>> >> > 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
>> >> > 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
>> >> > things could be automated.
>> > There's enough docstring manipulation going on already I think, this is
>> > that much work so manual would be better. It should be put in at the
>> > 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
>> >> 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
>> > between summary and extended summary would work. It should clearly state
>> > which version it will be removed. Best to keep the text identical to the
>> > passed to the deprecate decorator. A reason or alternative should be
>> > 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
>> SciPy-Dev mailing list
> 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)
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...
More information about the SciPy-Dev