On Aug 19, 2008, at 1:48 AM, Stéfan van der Walt wrote:
Wouldn't we want users to have access with the doc framework without doing anything special? And, yes, some of the documents are empty, but a number of them have already been written.
How do users know that those are present? How do users view those docs? You're the one who added that directory, yes?, so you've probably got the most experience with it. I couldn't figure out it, and the README in the doc/ directory wasn't helpful. [josiah:numpy/numpy/doc] dalke% svn log __init__.py ------------------------------------------------------------------------ r5371 | stefan | 2008-07-09 10:13:18 +0200 (Wed, 09 Jul 2008) | 2 lines Add numpy.doc topical documentation framework. The files with 1K bytes or less are undocumented -rw-r--r-- 1 dalke staff 307 Aug 3 00:59 __init__.py -rw-r--r-- 1 dalke staff 5203 Aug 15 17:44 basics.py -rw-r--r-- 1 dalke staff 5413 Aug 15 17:44 broadcasting.py -rw-r--r-- 1 dalke staff 5078 Aug 15 17:44 creation.py -rw-r--r-- 1 dalke staff 9854 Aug 15 17:44 glossary.py -rw-r--r-- 1 dalke staff 94 Aug 3 00:59 howtofind.py -rw-r--r-- 1 dalke staff 14286 Aug 15 17:44 indexing.py -rw-r--r-- 1 dalke staff 9608 Aug 15 17:44 internals.py -rw-r--r-- 1 dalke staff 82 Aug 3 00:59 io.py -rw-r--r-- 1 dalke staff 96 Aug 3 00:59 jargon.py -rw-r--r-- 1 dalke staff 130 Aug 3 00:59 methods_vs_functions.py -rw-r--r-- 1 dalke staff 81 Aug 3 00:59 misc.py -rw-r--r-- 1 dalke staff 100 Aug 3 00:59 performance.py -rw-r--r-- 1 dalke staff 7256 Aug 15 17:44 structured_arrays.py -rw-r--r-- 1 dalke staff 5520 Aug 15 17:44 ufuncs.py 8 documentation files, 6 placeholder files. I agree, the load time is very small. But with all my patches in place the import time goes down from about 0.18 second to about 0.10 seconds. Times add up.
I still think we are going about this the wrong way. We have two different sets of expectations, and we can't satisfy both by ripping everything apart. I'd much prefer two entry points into NumPy: one for people who need speed, and one for those who need the convenience of everything being at hand.
I thought I was very careful to not rip things apart. :( Everything I did was API compatible except for the proposed removals of numpy.ctypeslib and numpy.doc. I chose ctypeslib because importing ctypes takes 10% of the total load time on my box. I chose numpy.doc because I couldn't figure out how it's used. Now with Robert's go-ahead I'll also remove the "test" and "bench" entry points from everywhere except numpy.test and numpy.bench, so I will break some more compatibility. But not that "bench" doesn't currently work. I agree about two entry points but that's not going to happen by the next release. Actually, here's my quote from elsewhere in this discussion. I happen to think it's a mistake and there are other ways to have addressed the underlying requirement, but I know that's not going to change. (For example, follow matplotlib approach where there's a special library designed to be imported in interactive use. But I am *not* proposing this change.) I stressed the *not* because so far I've gone through: import Numeric import numarray import numpy and there's probably also a "from matplotlib import numerix" somewhere in there. It seems like every time I use num* (which isn't often) I need to learn a new library. I don't want to switch again for a few years. Andrew dalke@dalkescientific.com