Re: [SciPy-dev] Documenting Warnings
Personally, I think under Notes - with suitable emphasis, e.g., bracketed w/ double *'s, i.e., **Warning:** - would suffice. However, if it did exist in the standard and was removed, perhaps a summary of why could be added to the FAQ. DG --- On Fri, 6/26/09, Pierre GM <pgmdevlist@gmail.com> wrote:
From: Pierre GM <pgmdevlist@gmail.com> Subject: Re: [SciPy-dev] Documenting Warnings To: "SciPy Developers List" <scipy-dev@scipy.org> Date: Friday, June 26, 2009, 2:03 PM
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 ?
_______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On Fri, Jun 26, 2009 at 03:21:52PM -0700, David Goldsmith wrote:
Personally, I think under Notes - with suitable emphasis, e.g., bracketed w/ double *'s, i.e., **Warning:** - would suffice. However, if it did exist in the standard and was removed, perhaps a summary of why could be added to the FAQ.
I would say: under Notes, using sphinx standard: .. warning:: ... But I haven't check it works with our rendering pipeline. Gaël
On Jun 26, 2009, at 6:21 PM, David Goldsmith wrote:
Personally, I think under Notes - with suitable emphasis, e.g., bracketed w/ double *'s, i.e., **Warning:** - would suffice. However, if it did exist in the standard and was removed, perhaps a summary of why could be added to the FAQ.
The **...** method is not as good as a warning directive which displayed with a special template. Using a ..warning directive inside a 'Notes' might break things in numpydoc. There's already a _str_warnings in SphinxDocString, that transforms a "Warnings" section into a ..warning directive, why can't we use that ?
On Fri, Jun 26, 2009 at 7:11 PM, Pierre GM <pgmdevlist@gmail.com> wrote:
On Jun 26, 2009, at 6:21 PM, David Goldsmith wrote:
Personally, I think under Notes - with suitable emphasis, e.g., bracketed w/ double *'s, i.e., **Warning:** - would suffice. However, if it did exist in the standard and was removed, perhaps a summary of why could be added to the FAQ.
The **...** method is not as good as a warning directive which displayed with a special template.
agreed
Using a ..warning directive inside a 'Notes' might break things in numpydoc. There's already a _str_warnings in SphinxDocString, that transforms a "Warnings" section into a ..warning directive, why can't we use that ?
I looked in the ma module, the first example I found is http://docs.scipy.org/numpy/docs/numpy.ma.core.MaskedArray.cumsum The first line of Notes there does not need a big red box drawn around it, and be the standout visual element on the whole page. It's fine as a note saying: "pass in the wrong type --> something unexpected will happen". Some more thoughts: - if there are big red boxes on a lot of pages, a new user might think that NumPy is hard to use or beta quality. - all sections now have quite distinct purposes, while the line between Notes and Warnings is blurry. This will make the docs less uniform. - if you strongly feel something needs a big red box in a one-page docstring, you probably should raise an error after all. Can you give some examples where you think having warnings would really improve things? Cheers, Ralf
_______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On 2009-06-27, Ralf Gommers <ralf.gommers@googlemail.com> wrote: [clip]
Some more thoughts: - if there are big red boxes on a lot of pages, a new user might think that NumPy is hard to use or beta quality. - all sections now have quite distinct purposes, while the line between Notes and Warnings is blurry. This will make the docs less uniform. - if you strongly feel something needs a big red box in a one-page docstring, you probably should raise an error after all.
Some comments on this discussion: the warning:: directive will of course work without problems in all cases. The same goes for note:: and the other admonitions. I also don't think they look bad enough in text form to be avoided. I do not see a real need for a separate "Warnings" section. Typically, warnings are some points that you want to emphasize about something. I think these are better raised in vicinity of the context of the warning. If you want visual standouts, I think using the warning:: or note:: directives is appropriate. Also, the boundary between a warning as opposed to an ordinary note is a bit blurry here. For example: ... Parameters ---------- spam : ham_type Type of spam preferred. .. warning:: Giving `Ni` as `spam` will result to a permanent loss of cheese. ... is IMHO more appropriate than ... Parameters ---------- spam : ham_type Type of spam preferred. ... Warnings -------- Giving `Ni` as `spam` may result to a permanent loss of cheese. ... -- Pauli Virtanen
participants (5)
-
David Goldsmith -
Gael Varoquaux -
Pauli Virtanen -
Pierre GM -
Ralf Gommers