On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:

On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:

On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:

On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu> wrote:

On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
> As far as I know, stars are the only way to render a list in
> restructured txt, otherwise it looses the list formatting.

Try a definition list?
Example below.
Alan


Returns
-------

q, r if mode = 'full':

   - q : ndarray of float or complex, shape (M, K)
   - r : ndarray of float or complex, shape (K, N)

   K = min(M, N)

r if mode = 'r':
   - r : ndarray of float or complex, shape (K, N)

a2 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.

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

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'.

'optional' could be changed to 'conditional' or something like that.