[NumPy-Tickets] [NumPy] #1501: Addition to the docstring standard: an optional section for noting deprecation

[NumPy Trac]

#1501: Addition to the docstring standard: an optional section for noting
deprecation
--------------------------------------------+-------------------------------
 Reporter:  dgoldsmith                      |       Owner:  pv   
     Type:  enhancement                     |      Status:  new  
 Priority:  highest                         |   Milestone:  1.2.2
Component:  Documentation                   |     Version:       
 Keywords:  deprecation docstring standard  |  
--------------------------------------------+-------------------------------
 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 here.

 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?

-- 
Ticket URL: <http://projects.scipy.org/numpy/ticket/1501>
NumPy <http://projects.scipy.org/numpy>
My example project