[Numpy-discussion] Directives in numpy docstring convention

[Marc Garcia]

Hi there,

Is there a reason why the numpy docstring convention doesn't use the sphinx
directives .. deprecated:: [1] and .. seealso:: [2]?

I see that the numpy convention [3] uses the ..  note:: directive for the
deprecation notes, and for the "See also" it uses a section in this form:

See also
-------------

I guess those directives were added to the sphinx after the numpy docstring
convention was created. And in this case, while is probably not worth to
update numpy docstrings, I think they should be used for new projects that
want to follow the numpy convention. Is that the case, or is there a reason
why new projects shouldn't use them?

Thanks!

1. http://www.sphinx-doc.org/en/stable/markup/para.html#directive-deprecated
2. http://www.sphinx-doc.org/en/stable/markup/para.html#directive-seealso
3. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20171224/9031d557/attachment.html>