[SciPy-dev] Documenting Warnings
Sat Jun 27 10:53:52 CDT 2009
On Fri, Jun 26, 2009 at 7:11 PM, Pierre GM <firstname.lastname@example.org> 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.
> Using a ..warning directive inside a 'Notes' might break things in
> 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
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
> Scipy-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev