What about the undefined case (not a scalar, nor len in [2, n])?

My memory is a little haze, but if you put a double colon, and then indent the code, you will get a pretty code block if/when rendered with Sphinx.

remove "For"

And the leading .. ?

I keep getting sphinx syntax mixed up in my head. A directive is made up of a leading double dots, a space and a single word followed by double colons. Any arguments for that directive follow the double colons. "keyword" arguments (if any) are provided on the subsequent indented lines with the name of the keyword surrounded by colons and the value after it (see doc/api/index.rst for an example). Finally, any remaining indented text is treated as-is as a large string block.

It doesn't look like there is an ".. example::" directive, so I would re-write this part of the docstring as:

yerr[1] is error above *y*. For example::

@WeatherGod Where do I put the double dots in your example?

I followed the example below (from pyplot.py):

def figlegend(handles, labels, loc, **kwargs):
    """
    Place a legend in the figure.

    *labels*
      a sequence of strings

    *handles*
      a sequence of :class:`~matplotlib.lines.Line2D` or
      :class:`~matplotlib.patches.Patch` instances

    *loc*
      can be a string or an integer specifying the legend
      location

    A :class:`matplotlib.legend.Legend` instance is returned.

    Example::

      figlegend( (line1, line2, line3),
                 ('label1', 'label2', 'label3'),
                 'upper right' )

    .. seealso::

       :func:`~matplotlib.pyplot.legend`

    """
    l = gcf().legend(handles, labels, loc, **kwargs)
    draw_if_interactive()
    return l

I don't have sphinx, and I have no experience with it, so I'm deferring to you guys for epic sphinxage :)

You don't. Whenever you want to display a code block, you use just double-colons and indent the code block. You might also have to have a blank line as well. The word "example" before the double-colons is not special and can be any word. Sometimes, we even just use double colons on a line all by itself.