Directives in numpy docstring convention
![](https://secure.gravatar.com/avatar/b00a9ba0461bf84885675003b56878cb.jpg?s=120&d=mm&r=g)
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
![](https://secure.gravatar.com/avatar/da3a0a1942fbdc5ee9a9b8115ac5dae7.jpg?s=120&d=mm&r=g)
su, 2017-12-24 kello 18:51 +0000, Marc Garcia kirjoitti: [clip]
I guess those directives were added to the sphinx after the numpy docstring convention was created.
Just a comment on the historical point: the Numpy docstring standard existed before first Sphinx release. -- Pauli Virtanen
![](https://secure.gravatar.com/avatar/5f88830d19f9c83e2ddfd913496c5025.jpg?s=120&d=mm&r=g)
On Mon, Dec 25, 2017 at 7:51 AM, Marc Garcia <garcia.marc@gmail.com> wrote:
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. Ralf
![](https://secure.gravatar.com/avatar/da3a0a1942fbdc5ee9a9b8115ac5dae7.jpg?s=120&d=mm&r=g)
su, 2017-12-24 kello 18:51 +0000, Marc Garcia kirjoitti: [clip]
I guess those directives were added to the sphinx after the numpy docstring convention was created.
Just a comment on the historical point: the Numpy docstring standard existed before first Sphinx release. -- Pauli Virtanen
![](https://secure.gravatar.com/avatar/5f88830d19f9c83e2ddfd913496c5025.jpg?s=120&d=mm&r=g)
On Mon, Dec 25, 2017 at 7:51 AM, Marc Garcia <garcia.marc@gmail.com> wrote:
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. Ralf
participants (3)
-
Marc Garcia
-
Pauli Virtanen
-
Ralf Gommers