Documenting Warnings
All, How do we document a warning, a note that should be displayed differently as a note ? Don't we have a "Warnings" entry in the docstrings standard ? Thx
On Fri, Jun 26, 2009 at 3:24 PM, Pierre GM <pgmdevlist@gmail.com> wrote:
All, How do we document a warning, a note that should be displayed differently as a note ? Don't we have a "Warnings" entry in the docstrings standard ? Thx
For longer reST doc files you can use (see for example http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/): *.. warning:: Description. *There is no Warnings heading in the docstring standard. Why can't you put it either under Notes or under Raises? And special reST markup like the above is discouraged in docstrings because it looks bad on text terminals. Cheers, Ralf
On Jun 26, 2009, at 4:48 PM, Ralf Gommers wrote:
On Fri, Jun 26, 2009 at 3:24 PM, Pierre GM <pgmdevlist@gmail.com> wrote: All, How do we document a warning, a note that should be displayed differently as a note ? Don't we have a "Warnings" entry in the docstrings standard ? Thx
For longer reST doc files you can use (see for example http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/) :
.. warning::
Description.
Meh. Not the best as you pointed out.
There is no Warnings heading in the docstring standard.
I've noticed that and regret it.
Why can't you put it either under Notes or under Raises?
Because you may want to stress one particular aspect that would otherwise be easy to overlook in a Notes. Because you want to describe a known limitation that doesn't raise any exception (and maybe not even a warning per se: in that case, I'd put in the Raises section as you suggest). [FYI, I was just checking recent updates in the docstrings of numpy.ma and noticed that Pauli got rid of the Warnings section and merged it in a Notes. I still think that the two sections shouldn't have been merged, but I won't lose sleep over it. I'm just curious).
And special reST markup like the above is discouraged in docstrings because it looks bad on text terminals.
So why don't we have a Warning entry in the docsring standard ? Pauli, what are your thoughts about that ? I know for a fact that it'd be quite easy to implement. Any strong reason against that ?
2009/6/26 Pierre GM <pgmdevlist@gmail.com>:
On Jun 26, 2009, at 4:48 PM, Ralf Gommers wrote:
Why can't you put it either under Notes or under Raises?
Because you may want to stress one particular aspect that would otherwise be easy to overlook in a Notes. Because you want to describe a known limitation that doesn't raise any exception (and maybe not even a warning per se: in that case, I'd put in the Raises section as you suggest).
[FYI, I was just checking recent updates in the docstrings of numpy.ma and noticed that Pauli got rid of the Warnings section and merged it in a Notes. I still think that the two sections shouldn't have been merged, but I won't lose sleep over it. I'm just curious).
I'm also guilty of mangling your docstrings in this way, so that they'd match the standard. Including an optional warnings section in the standard sounds like a good idea to me.. Cheers, Scott
participants (3)
-
Pierre GM
-
Ralf Gommers
-
Scott Sinclair