[SciPy-dev] Summer Doc Marathon status report and request for more writers

[Pauli Virtanen]

Sat, 05 Jul 2008 00:54:56 -0700, Andrew Straw wrote:

> One thing I notice about the organization of the doc site that seems
> sub-optimal is that functions are resolved to the module where they're
> defined rather than their canonical namespace. In particular, clicking
> on the page for array() from the main numpy page gives me a page with
> the primary header saying "numpy.core.multiarray.array". I think that's
> confusing, particularly to new users. All the more so since I believe
> the "numpy.core" namespace is more-or-less for internal implementation
> and it is discouraged to write external code referencing into
> numpy.core.

It's a kind of a feature: a "canonical namespace" is not a well-defined 
concept, so it makes sense for the program to use the location where the 
object is defined as a "canonical name". This is always unique and it's 
actually possible to deduce it automatically just by looking at the 
Python object. So, there are technical reasons for using it.

But I think you're referring more to the names appearing in the UI than 
the internal architecture. It is possible to map the names displayed to 
the aliases with the least number of dots, which I guess is as close to a 
"canonical namespace" as you can automatically get.

-- 
Pauli Virtanen