[Numpy-discussion] Code samples in docstrings mistaken as doctests

Michael McNeil Forbes mforbes@physics.ubc...
Mon Jun 23 15:04:45 CDT 2008


> On 23 Jun 2008, at 12:37 PM, Alan McIntyre wrote:
>> Ugh.  That just seems like a lot of unreadable ugliness to me.  If
>> this comment magic is the only way to make that stuff execute  
>> properly
>> under doctest, I think I'd rather just skip it in favor of clean,
>> uncluttered, non-doctestable code samples in the docstrings.

Another perspective: doctests ensure that documentation stays up to  
date (if the behaviour or interface changes, then tests will fail  
indicating that the documentation also needs to be updated.)

Thus, one can argue that all examples should also be doctests.  This  
generally makes things a little more ugly, but much less ambiguous.

...
Examples:
---------
If A, B, C, and D are appropriately shaped 2-d arrays, then one can  
produce

     [ A  B ]
     [ C  D ]

using any of these methods:
 >>> A, B, C, D = [[1,1]], [[2,2]], [[3,3]], [[4,4]]
 >>> np.bmat('A, B; C, D')                  # From a string
matrix([[ 1,  1,  2,  2],
         [ 3,  3,  4,  4]])
 >>> np.bmat([[A,B],[C,D]])                 # From a nested sequence
matrix([[ 1,  1,  2,  2],
         [ 3,  3,  4,  4]])
 >>> np.bmat(np.r_[np.c_[A,B],np.c_[C,D]])  # From an array
matrix([[ 1,  1,  2,  2],
         [ 3,  3,  4,  4]])

Michael.


More information about the Numpy-discussion mailing list