[SciPy-dev] Documenting Warnings

[Pauli Virtanen]

On 2009-06-27, Ralf Gommers <ralf.gommers at 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