[SciPy-dev] Documenting Warnings

[Pierre GM]

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 ?