[Numpy-discussion] Help!!! Docstrings overrun by markup crap.
Charles R Harris
charlesr.harris at gmail.com
Sun Mar 21 10:23:09 EDT 2010
On Sun, Mar 21, 2010 at 8:01 AM, Ralf Gommers
<ralf.gommers at googlemail.com>wrote:
>
>
> On Sun, Mar 21, 2010 at 9:58 PM, Ralf Gommers <ralf.gommers at googlemail.com
> > wrote:
>
>>
>>
>> On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac at american.edu>wrote:
>>
>>> On 3/21/2010 12:54 AM, Ralf Gommers wrote:
>>> > too many blank lines are needed
>>>
>>> Please define "need" after seeing the compact example I posted.
>>>
>>> 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.
>>
>
> This line in the code is fairly amusing by the way:
> # economic mode. Isn't actually economic.
>
> Economic mode is very similar to 'r' mode anyway, what's the point?
>
>
Economic mode is what the low level algorithm likely returns, it contains
the info needed to contruct q if needed, or to efficiently apply q to
different vectors without constructing q; constructing q adds to the
computational and memory costs, as does pulling r out of the economic
return. The situation is analogous to the LU decomposition where the natural
form is to store both L and U in the original matrix. Other algorithms can
then use that compact form to solve equations with different right hand
sides.
Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100321/4671e10c/attachment.html>
More information about the NumPy-Discussion
mailing list