[Numpy-discussion] Where to put versionadded

Charles R Harris charlesr.harris at gmail.com
Fri Apr 4 14:12:06 EDT 2014


Hi All,

Currently there are several placements of the '.. versionadded::' directive
and I'd like to settle
on a proper style for consistency. There are two occasions on which it is
used, first, when a new function or class is added and second, when a new
keyword is added to an existing function or method. The options are as
follows.

*New Function*

1) Originally, the directive was added in the notes section.

Notes
-----
.. versionadded:: 1.5.0

 2) Alternatively, it is placed after the extended summary.

blah, blah

..versionadded:: 1.5.0

Between these two, I vote for 2) because the version is easily found when
reading the documentation either in a terminal or rendered into HTML.

*New Parameter*

1) It is placed before the parameter description

newoption : int, optional
    .. versionadded:: 1.5.0
    blah.

2) It is placed after the parameter description.

newoption : int, optional
    blah.

    .. versionadded:: 1.5.0

Both of these render correctly, but the first is more compact while the
second puts the version
after the description where it doesn't interrupt the reading. I'm tending
towards 1) on account of its compactness.

Thoughts?

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20140404/626fe2d9/attachment.html>


More information about the NumPy-Discussion mailing list