Example,

ааа Compute the qr factorization of a matrix.
ааа
ааа Factor the matrix a as qr, where q is orthonormal
ааа (:math:dot( q_{:,i}, q_{:,j}) = \delta_{ij}, the Kronecker delta) and
ааа r is upper-triangular.

Arrggghhhh... Totally. Unreadable. Why not say the columns of q are orthonormal vectors and r is upper triangular? The math tutorial should go in the notes, if anywhere. Might mention that this is a 'thin' factorization (Golub). Let me propose a rule: no math markup in the summary, ever.

ааа Parameters
ааа ----------
ааа a : array_like, shape (M, N)
ааааааа Matrix to be factored.
ааа mode : {'full', 'r', 'economic'}
ааааааа Specifies the information to be returned. 'full' is the default.
ааааааа mode='r' returns a "true" r, while 'economic' returns a "polluted"
ааааааа r (albeit slightly faster; see Returns below).
ааа

Oh, come now, "true", "polluted"? Sounds a bit political... Actually, 'economic' contains info on the Householder reflections. In any case, why mention it at all, just refer to the return documentation. And wouldn't values be a better word than information?
а
ааа Returns
ааа -------
ааа * If mode = 'full':
ааа
ааааааа * q : ndarray of float or complex, shape (M, K)
ааааааа * r : ndarray of float or complex, shape (K, N)
ааа
ааааа Size K = min(M, N)
ааа
ааа * If mode = 'r':
ааа
ааааа * r : ndarray of float or complex, shape (K, N)
ааа
ааа * If mode = 'economic':
ааа
ааааа * a2 : ndarray of float or complex, shape (M, N)
ааа
ааааа The diagonal and the upper triangle of a2 contains r,
ааааа while the rest of the matrix is undefined.

WTF? I'm seeing stars.

I may be old and crotchety, and I don't mean to be mean to the folks who have done the hard work to bring the docstring to its current state, but I think things have gotten out of hand.

Chuck