[SciPy-dev] Documenting Warnings

Ralf Gommers ralf.gommers@googlemail....
Sat Jun 27 10:53:52 CDT 2009


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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090627/540ed0b2/attachment.html 


More information about the Scipy-dev mailing list