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

[David Goldsmith]

On Thu, Jun 3, 2010 at 11:18 AM, David Goldsmith <d.l.goldsmith at gmail.com>
wrote:
>
> http://projects.scipy.org/numpy/ticket/1501
>
> Filed Description:
>
> "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
rectified.
>
> "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
like).
>
> "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 the latest.
>
> "Have I forgotten anything"
>
> DG

Well, the deadline is upon us; here's my concrete proposal:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standardshould
be modified as follows:

*Present Content*
     :
Sections

The sections of the docstring are:

1.  *Short summary*...

*Proposed Content*
     :
Sections

The sections of the docstring are:

0.  *Deprecation warning* (optional, but required if the object is
designated for deprecation)

     .. deprecated:: <*deprecation schedule*>, <*justification, if known*>
(optional), <*functional equivalents, if extant*> (optional), <*example*>

1.  *Sort summary*...

To submit this as a patch, do I grab HOWTO_DOCUMENT.txt, modify it, then
attach the modified version as an attachment to the ticket?

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100615/43204fe8/attachment.html>