Maybe handle it in a manner similar to the other sections.

q,r <> mode = 'r''
    q: [M,N] ndarray
        The columns of 'q' are orthonomal.
    r:  [K,N] ndarray
        Upper triangular array.
...

The "<>" standing in for "if". The indentation could be moved out.

Looks good, but what determines that this is a list, the <>? What if you want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.

That was just a suggestion, I think it can probably be improved upon. Thoughts?

In general a list should just be defined with *. Like:
* item 1
    * sub-item 1
      Hey, a multi-line sub-item works too!
    * sub-item 2
* item 2

I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO). Unlike dashes, colons, and underlines they aren't part of the usual textual repetoire.

 

In the specific case of a variable number of return values, I do not like the if..else construction. How about this:

q : ndarray
    The q-value. If mode='r' this contains ....
    If mode='economic' ....
r : ndarray, optional
    The r-value. Is only returned if mode='r'.

In the case at hand, q is optional and r has two forms.