[Numpy-discussion] Improving Docs on Wiki

[Joe Harrington]

> Is it perhaps possible to make all numpy functions accessible in
> submodules (in addition to in numpy, for backwards compatibility) and
> then promote accessing them that way?

I would caution on breaking functionality out into too many
categories.

It is *very* cumbersome to constantly import little groups of
functions to get anything done, and it presents a particular
learning-curve hurdle for students.  Unless you load into the
top-level namespace, which I discourage, it also gets cumbersome to be
typing N.X.Y.Z.sort(), because it means you have to memorize that
sort() is in N.X.Y.Z but sinc() is in N.A.B.C.  Your thinking also
gets removed from the verb you are familiar with.  The fewer
useless adornments code has, the better.

It's also hard to find stuff if it's not loaded, and when you get to
subgroups of subgroups, there is no easy way even to know that
something exists.  For example, if you have scipy.x.y, and you're not
an advanced enough user to know that y is related to x (say, filtering
as a subcategory of fft), you hunt around for an hour and then say,
sheesh, scipy can't even filter, when of course it can, you just
didn't think to load the fft package.  (I know this isn't the
structure for these specific topics, but you get the idea).  You can
waste hours this way, especially if you find it embarrassing to ask
for help, which many do.

What you have brought up is really a documentation problem: how do I
find the name of the routine I want?  Languages like IDL have
documentation search capabilities that we don't yet have.  They also
have indexes of related routines in both printed form and online.  We
need these, they're not too hard to do, and if plans work out, they'll
be done as part of a project I'm putting together for the summer (stay
tuned for an announcement and request for help in the coming weeks).

There is value in python's namespace capability, but I find that it's
more in the vein of allowing separate groups to develop functions with
sensible names and not worry about a conflict.  When people make
numerous tiny categories, it becomes a memorization and extra typing
exercise, and it steepens the learning curve substantially.  We can
and will break these functions out into small categories, but it's
much better to do it in lists that you'll be able to call up rather
than in the structure of the language.

--jh--