On Mon, Dec 25, 2017 at 7:51 AM, Marc Garcia <garcia.m...@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. Ralf > > 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@python.org > https://mail.python.org/mailman/listinfo/numpy-discussion > >
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
