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

Vincent Davis vincent@vincentdavis....
Tue Jun 15 22:02:00 CDT 2010


On Tue, Jun 15, 2010 at 8:55 PM, David Goldsmith
<d.l.goldsmith@gmail.com> wrote:
> On Thu, Jun 3, 2010 at 11:18 AM, David Goldsmith <d.l.goldsmith@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-standard
> should 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?
>

You must have had that on your calendar. It looks good to me.

Vincent


> DG
>
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>


More information about the SciPy-Dev mailing list