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