[Numpy-discussion] Directives in numpy docstring convention

Ralf Gommers ralf.gommers at gmail.com
Mon Dec 25 20:48:34 EST 2017

On Mon, Dec 25, 2017 at 7:51 AM, Marc Garcia <garcia.marc at gmail.com> wrote:

> 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?

If you prefer the way those Sphinx directives are rendered, then I don't
see a problem with using them. I think our recommendation would be to keep
to the NumPy docstring standard however; that'll get rendered like the docs
for all core packages in the ecosystem.


> 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
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20171226/a54be15c/attachment.html>

More information about the NumPy-Discussion mailing list