Move documentation outside of source tree. Remove `doc` import from __init__.

1 files changed, 132 insertions, 0 deletions

diff --git a/numpy/doc/creation.py b/numpy/doc/creation.py
new file mode 100644
index 000000000..1e80e5115
--- /dev/null
+++ b/numpy/doc/creation.py
@@ -0,0 +1,132 @@
+"""
+==============
+Array creation
+==============
+
+Introduction
+============
+
+There are 5 general mechanisms for creating arrays:
+
+1) Conversion from other Python structures (e.g., lists, tuples)
+2) Intrinsic numpy array array creation objects (e.g., arange, ones, zeros, etc.)
+3) Reading arrays from disk, either from standard or custom formats
+4) Creating arrays from raw bytes through the use of strings or buffers
+5) Use of special library functions (e.g., random)
+
+This section will not cover means of replicating, joining, or otherwise
+expanding or mutating existing arrays. Nor will it cover creating object
+arrays or record arrays. Both of those are covered in their own sections.
+
+Converting Python array-like objects to numpy arrays
+====================================================
+
+In general, numerical data arranged in an array-like structure in Python can
+be converted to arrays through the use of the array() function. The most obvious
+examples are lists and tuples. See the documentation for array() for details for
+its use. Some
+objects may support the array-protocol and allow conversion to arrays this
+way. A simple way to find out if the object can be converted to a numpy array
+using array() is simply to try it interactively and see if it works! (The
+Python Way).
+
+Examples: ::
+
+ >>> x = np.array([2,3,1,0])
+ >>> x = np.array([2, 3, 1, 0])
+ >>> x = np.array([[1,2.0],[0,0],(1+1j,3.)]) # note mix of tuple and lists, and types
+ >>> x = np.array([[ 1.+0.j, 2.+0.j], [ 0.+0.j, 0.+0.j], [ 1.+1.j, 3.+0.j]])
+
+Intrinsic numpy array creation
+==============================
+
+Numpy has built-in functions for creating arrays from scratch:
+
+zeros(shape) will create an array filled with 0 values with the specified
+shape. The default dtype is float64.
+
+``>>> np.zeros((2, 3))
+array([[ 0., 0., 0.], [ 0., 0., 0.]])``
+
+ones(shape) will create an array filled with 1 values. It is identical to
+zeros in all other respects.
+
+arange() will create arrays with regularly incrementing values. Check the
+docstring for complete information on the various ways it can be used. A few
+examples will be given here: ::
+
+ >>> np.arange(10)
+ array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+ >>> np.arange(2, 10, dtype=np.float)
+ array([ 2., 3., 4., 5., 6., 7., 8., 9.])
+ >>> np.arange(2, 3, 0.1)
+ array([ 2. , 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9])
+
+Note that there are some subtleties regarding the last usage that the user
+should be aware of that are described in the arange docstring.
+
+indices() will create a set of arrays (stacked as a one-higher dimensioned
+array), one per dimension with each representing variation in that dimension.
+An examples illustrates much better than a verbal description: ::
+
+ >>> np.indices((3,3))
+ array([[[0, 0, 0], [1, 1, 1], [2, 2, 2]], [[0, 1, 2], [0, 1, 2], [0, 1, 2]]])
+
+This is particularly useful for evaluating functions of multiple dimensions on
+a regular grid.
+
+Reading arrays from disk
+========================
+
+This is presumably the most common case of large array creation. The details,
+of course, depend greatly on the format of data on disk and so this section
+can only give general pointers on how to handle various formats.
+
+Standard binary formats
+-----------------------
+
+Various fields have standard formats for array data. The following lists the
+ones with known python libraries to read them and return numpy arrays (there
+may be others for which it is possible to read and convert to numpy arrays so
+check the last section as well)
+
+HDF5: PyTables
+FITS: PyFITS
+Others? xxx
+
+Examples of formats that cannot be read directly but for which it is not hard
+to convert are libraries like PIL (able to read and write many image formats
+such as jpg, png, etc).
+
+Common ascii formats
+--------------------
+
+Comma Separated Value files (CSV) are widely used (and an export and import
+option for programs like Excel). There are a number of ways of reading these
+files in Python. The most convenient ways of reading these are found in pylab
+(part of matplotlib) in the xxx function. (list alternatives xxx)
+
+More generic ascii files can be read using the io package in scipy. xxx a few
+more details needed...
+
+Custom binary formats
+---------------------
+
+There are a variety of approaches one can use. If the file has a relatively
+simple format then one can write a simple I/O library and use the numpy
+fromfile() function and .tofile() method to read and write numpy arrays
+directly (mind your byteorder though!) If a good C or C++ library exists that
+read the data, one can wrap that library with a variety of techniques (see
+xxx) though that certainly is much more work and requires significantly more
+advanced knowledge to interface with C or C++.
+
+Use of special libraries
+------------------------
+
+There are libraries that can be used to generate arrays for special purposes
+and it isn't possible to enumerate all of them. The most common uses are use
+of the many array generation functions in random that can generate arrays of
+random values, and some utility functions to generate special matrices (e.g.
+diagonal, see xxx)
+
+"""