You need 4 blank lines in your example. Now I tried adding a description for the first argument (q) like this:
q, r if mode = 'full' :
   - q : ndarray of float or complex, shape (M, K)
         Description of `q`.
   - r : ndarray of float or complex, shape (K, N)

That doesn't work, you need yet more blank lines (try this in the wiki editor).


I just changed the docstring to the following, looks much better in both plain text and html imho:

q : ndarray of float or complex, optional
    The orthonormal matrix, of shape (M, K). Only returned if
    ``mode='full'``.
r : ndarray of float or complex, optional
    The upper-triangular matrix, of shape (K, N) with K = min(M, N).
    Only returned when ``mode='full'`` or ``mode='r'``.
a2 : ndarray of float or complex, optional
    Array of shape (M, N), only returned when ``mode='economic``'.
    The  diagonal and the upper triangle of `a2` contains `r`, while
    the rest of the matrix is undefined.