From 1c7167378e9f654a80b3cb57b7c0dd7ee573a109 Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Wed, 17 Feb 2010 23:55:16 +0000 Subject: updated documentation from pydoc website (thanks to everyone who contributed!) --- doc/source/user/basics.indexing.rst | 7 ---- doc/source/user/basics.rec.rst | 2 ++ doc/source/user/basics.rst | 5 --- doc/source/user/basics.types.rst | 7 ---- doc/source/user/c-info.beyond-basics.rst | 54 +++++++++++++++------------- doc/source/user/c-info.python-as-glue.rst | 17 +++++---- doc/source/user/howtofind.rst | 2 -- doc/source/user/install.rst | 58 ++++++++++++++++--------------- doc/source/user/misc.rst | 2 -- doc/source/user/performance.rst | 2 -- 10 files changed, 69 insertions(+), 87 deletions(-) (limited to 'doc/source/user') diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst index f218fd060..8844adcae 100644 --- a/doc/source/user/basics.indexing.rst +++ b/doc/source/user/basics.indexing.rst @@ -6,11 +6,4 @@ Indexing .. seealso:: :ref:`Indexing routines ` -.. note:: - - XXX: Combine ``numpy.doc.indexing`` with material - section 2.2 Basic indexing? - Or incorporate the material directly here? - - .. automodule:: numpy.doc.indexing diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst index 81a3de8e3..ce6c3b851 100644 --- a/doc/source/user/basics.rec.rst +++ b/doc/source/user/basics.rec.rst @@ -1,3 +1,5 @@ +.. _structured_arrays: + *************************************** Structured arrays (aka "Record arrays") *************************************** diff --git a/doc/source/user/basics.rst b/doc/source/user/basics.rst index 85e79c25d..bbc3ab174 100644 --- a/doc/source/user/basics.rst +++ b/doc/source/user/basics.rst @@ -2,11 +2,6 @@ Numpy basics ************ -.. note:: - - XXX: there is overlap between this text extracted from ``numpy.doc`` - and "Guide to Numpy" chapter 2. Needs combining? - .. toctree:: :maxdepth: 2 diff --git a/doc/source/user/basics.types.rst b/doc/source/user/basics.types.rst index 4982045a2..5ce5af15a 100644 --- a/doc/source/user/basics.types.rst +++ b/doc/source/user/basics.types.rst @@ -4,11 +4,4 @@ Data types .. seealso:: :ref:`Data type objects ` -.. note:: - - XXX: Combine ``numpy.doc.indexing`` with material from - "Guide to Numpy" (section 2.1 Data-Type descriptors)? - Or incorporate the material directly here? - - .. automodule:: numpy.doc.basics diff --git a/doc/source/user/c-info.beyond-basics.rst b/doc/source/user/c-info.beyond-basics.rst index 703124b58..563467e72 100644 --- a/doc/source/user/c-info.beyond-basics.rst +++ b/doc/source/user/c-info.beyond-basics.rst @@ -159,17 +159,18 @@ Broadcasting over multiple arrays .. index:: single: broadcasting -When multiple arrays are involved in an operation, you may want to use the same -broadcasting rules that the math operations ( *i.e.* the ufuncs) use. This can -be done easily using the :ctype:`PyArrayMultiIterObject`. This is the object -returned from the Python command numpy.broadcast and it is almost as easy to -use from C. The function :cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is -used (with ``n`` input objects in place of ``...`` ). The input objects can be -arrays or anything that can be converted into an array. A pointer to a -PyArrayMultiIterObject is returned. Broadcasting has already been accomplished -which adjusts the iterators so that all that needs to be done to advance to the -next element in each array is for PyArray_ITER_NEXT to be called for each of -the inputs. This incrementing is automatically performed by +When multiple arrays are involved in an operation, you may want to use the +same broadcasting rules that the math operations (*i.e.* the ufuncs) use. +This can be done easily using the :ctype:`PyArrayMultiIterObject`. This is +the object returned from the Python command numpy.broadcast and it is almost +as easy to use from C. The function +:cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is used (with ``n`` input +objects in place of ``...`` ). The input objects can be arrays or anything +that can be converted into an array. A pointer to a PyArrayMultiIterObject is +returned. Broadcasting has already been accomplished which adjusts the +iterators so that all that needs to be done to advance to the next element in +each array is for PyArray_ITER_NEXT to be called for each of the inputs. This +incrementing is automatically performed by :cfunc:`PyArray_MultiIter_NEXT` ( ``obj`` ) macro (which can handle a multiterator ``obj`` as either a :ctype:`PyArrayMultiObject *` or a :ctype:`PyObject *`). The data from input number ``i`` is available using @@ -233,15 +234,19 @@ can be used. The function call used to create a new ufunc to work on built-in data-types is given below. A different mechanism is used to register ufuncs for user-defined data-types. -.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return) +.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, + void** data, char* types, int ntypes, int nin, int nout, int identity, + char* name, char* doc, int check_return) *func* A pointer to an array of 1-d functions to use. This array must be at - least ntypes long. Each entry in the array must be a ``PyUFuncGenericFunction`` function. This function has the following signature. An example of a - valid 1d loop function is also given. + least ntypes long. Each entry in the array must be a + ``PyUFuncGenericFunction`` function. This function has the following + signature. An example of a valid 1d loop function is also given. - .. cfunction:: void loop1d(char** args, npy_intp* dimensions, npy_intp* steps, void* data) + .. cfunction:: void loop1d(char** args, npy_intp* dimensions, + npy_intp* steps, void* data) *args* @@ -269,7 +274,8 @@ register ufuncs for user-defined data-types. .. code-block:: c static void - double_add(char *args, npy_intp *dimensions, npy_intp *steps, void *extra) + double_add(char *args, npy_intp *dimensions, npy_intp *steps, + void *extra) { npy_intp i; npy_intp is1=steps[0], is2=steps[1]; @@ -320,9 +326,9 @@ register ufuncs for user-defined data-types. *identity* - Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, :cdata:`PyUFunc_None`. - This specifies what should be returned when an empty array is - passed to the reduce method of the ufunc. + Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, + :cdata:`PyUFunc_None`. This specifies what should be returned when + an empty array is passed to the reduce method of the ufunc. *name* @@ -458,7 +464,8 @@ functions for each conversion you want to support and then registering these functions with the data-type descriptor. A low-level casting function has the signature. -.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr, void* toarr) +.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr, + void* toarr) Cast ``n`` elements ``from`` one type ``to`` another. The data to cast from is in a contiguous, correctly-swapped and aligned chunk @@ -531,7 +538,8 @@ previously created. Then you call :cfunc:`PyUFunc_RegisterLoopForType` this function is ``0`` if the process was successful and ``-1`` with an error condition set if it was not successful. -.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) +.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc, + int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) *ufunc* @@ -661,10 +669,6 @@ Specific features of ndarray sub-typing Some special methods and attributes are used by arrays in order to facilitate the interoperation of sub-types with the base ndarray type. -.. note:: XXX: some of the documentation below needs to be moved to the - reference guide. - - The __array_finalize\__ method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/user/c-info.python-as-glue.rst b/doc/source/user/c-info.python-as-glue.rst index 4fb337821..6ce266859 100644 --- a/doc/source/user/c-info.python-as-glue.rst +++ b/doc/source/user/c-info.python-as-glue.rst @@ -13,7 +13,7 @@ Using Python as glue Many people like to say that Python is a fantastic glue language. Hopefully, this Chapter will convince you that this is true. The first adopters of Python for science were typically people who used it to -glue together large applicaton codes running on super-computers. Not +glue together large application codes running on super-computers. Not only was it much nicer to code in Python than in a shell script or Perl, in addition, the ability to easily extend Python made it relatively easy to create new classes and types specifically adapted @@ -123,8 +123,7 @@ F2py allows you to automatically construct an extension module that interfaces to routines in Fortran 77/90/95 code. It has the ability to parse Fortran 77/90/95 code and automatically generate Python signatures for the subroutines it encounters, or you can guide how the -subroutine interfaces with Python by constructing an interface- -defintion-file (or modifying the f2py-produced one). +subroutine interfaces with Python by constructing an interface-definition-file (or modifying the f2py-produced one). .. index:: single: f2py @@ -175,7 +174,7 @@ be imported from Python:: This command leaves a file named add.{ext} in the current directory (where {ext} is the appropriate extension for a python extension module on your platform --- so, pyd, *etc.* ). This module may then be -imported from Python. It will contain a method for each subroutin in +imported from Python. It will contain a method for each subroutine in add (zadd, cadd, dadd, sadd). The docstring of each method contains information about how the module method may be called: @@ -586,7 +585,7 @@ produce a robust but fast subroutine. One final note about weave.inline: if you have additional code you want to include in the final extension module such as supporting -function calls, include statments, etc. you can pass this code in as a +function calls, include statements, etc. you can pass this code in as a string using the keyword support_code: ``weave.inline(code, variables, support_code=support)``. If you need the extension module to link against an additional library then you can also pass in @@ -784,7 +783,7 @@ details. Pyrex-filter ------------ -The two-dimensional example we created using weave is a bit uglierto +The two-dimensional example we created using weave is a bit uglier to implement in Pyrex because two-dimensional indexing using Pyrex is not as simple. But, it is straightforward (and possibly faster because of pre-computed indices). Here is the Pyrex-file I named image.pyx. @@ -873,7 +872,7 @@ There are several disadvantages of using Pyrex: 4. Multi-dimensional arrays are "bulky" to index (appropriate macros may be able to fix this). -5. The C-code generated by Prex is hard to read and modify (and typically +5. The C-code generated by Pyrex is hard to read and modify (and typically compiles with annoying but harmless warnings). Writing a good Pyrex extension module still takes a bit of effort @@ -1126,8 +1125,8 @@ significantly safer to call a C-function using ctypes and the data- area of an ndarray. You may still want to wrap the function in an additional Python wrapper to make it user-friendly (hiding some obvious arguments and making some arguments output arguments). In this -process, the **requires** function in NumPy may be useful to return the right kind of array from -a given input. +process, the **requires** function in NumPy may be useful to return the right +kind of array from a given input. Complete example diff --git a/doc/source/user/howtofind.rst b/doc/source/user/howtofind.rst index 5f6b49012..00ed5daa7 100644 --- a/doc/source/user/howtofind.rst +++ b/doc/source/user/howtofind.rst @@ -4,6 +4,4 @@ How to find documentation .. seealso:: :ref:`Numpy-specific help functions ` -.. note:: XXX: this part is not yet written. - .. automodule:: numpy.doc.howtofind diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst index 1941ebb29..06b2115da 100644 --- a/doc/source/user/install.rst +++ b/doc/source/user/install.rst @@ -12,29 +12,30 @@ Windows ------- Good solutions for Windows are, The Enthought Python Distribution `(EPD) -`_ (which provides binary installers -for Windows, OS X and Redhat) and `Python (x, y) `_. -Both of these packages include Python, NumPy and many additional packages. -A lightweight alternative is to download the Python installer from -`www.python.org `_ and the NumPy installer for your -Python version from the Sourceforge `download site -`_ +`_ (which provides binary +installers for Windows, OS X and Redhat) and `Python (x, y) +`_. Both of these packages include Python, NumPy and +many additional packages. A lightweight alternative is to download the Python +installer from `www.python.org `_ and the NumPy +installer for your Python version from the Sourceforge `download site `_ Linux ----- Most of the major distributions provide packages for NumPy, but these can lag behind the most recent NumPy release. Pre-built binary packages for Ubuntu are -available on the `scipy ppa `_. -Redhat binaries are available in the `EPD -`_. +available on the `scipy ppa +`_. Redhat binaries are +available in the `EPD `_. Mac OS X -------- A universal binary installer for NumPy is available from the `download site -`_. -The `EPD `_ provides NumPy binaries. +`_. The `EPD `_ +provides NumPy binaries. Building from source ==================== @@ -62,21 +63,22 @@ Building NumPy requires the following software installed: 2) Compilers - To build any extension modules for Python, you'll need a C compiler. Various - NumPy modules use FORTRAN 77 libraries, so you'll also need a FORTRAN 77 - compiler installed. + To build any extension modules for Python, you'll need a C compiler. + Various NumPy modules use FORTRAN 77 libraries, so you'll also need a + FORTRAN 77 compiler installed. - Note that NumPy is developed mainly using GNU compilers. Compilers from other - vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, Lahey, HP, - IBM, Microsoft are only supported in the form of community feedback, and may - not work out of the box. GCC 3.x (and later) compilers are recommended. + Note that NumPy is developed mainly using GNU compilers. Compilers from + other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, + Lahey, HP, IBM, Microsoft are only supported in the form of community + feedback, and may not work out of the box. GCC 3.x (and later) compilers + are recommended. 3) Linear Algebra libraries - NumPy does not require any external linear algebra libraries to be installed. - However, if these are available, NumPy's setup script can detect them and use - them for building. A number of different LAPACK library setups can be used, - including optimized LAPACK libraries such as ATLAS, MKL or the + NumPy does not require any external linear algebra libraries to be + installed. However, if these are available, NumPy's setup script can detect + them and use them for building. A number of different LAPACK library setups + can be used, including optimized LAPACK libraries such as ATLAS, MKL or the Accelerate/vecLib framework on OS X. FORTRAN ABI mismatch @@ -87,8 +89,8 @@ Unfortunately, they are not ABI compatible, which means that concretely you should avoid mixing libraries built with one with another. In particular, if your blas/lapack/atlas is built with g77, you *must* use g77 when building numpy and scipy; on the contrary, if your atlas is built with gfortran, you -*must* build numpy/scipy with gfortran. This applies for most other cases where -different FORTRAN compilers might have been used. +*must* build numpy/scipy with gfortran. This applies for most other cases +where different FORTRAN compilers might have been used. Choosing the fortran compiler ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -110,9 +112,9 @@ How to check the ABI of blas/lapack/atlas One relatively simple and reliable way to check for the compiler used to build a library is to use ldd on the library. If libg2c.so is a dependency, this -means that g77 has been used. If libgfortran.so is a a dependency, gfortran has -been used. If both are dependencies, this means both have been used, which is -almost always a very bad idea. +means that g77 has been used. If libgfortran.so is a a dependency, gfortran +has been used. If both are dependencies, this means both have been used, which +is almost always a very bad idea. Building with ATLAS support --------------------------- diff --git a/doc/source/user/misc.rst b/doc/source/user/misc.rst index 4e2ec9fdb..0e1807f3f 100644 --- a/doc/source/user/misc.rst +++ b/doc/source/user/misc.rst @@ -2,8 +2,6 @@ Miscellaneous ************* -.. note:: XXX: This section is not yet written. - .. automodule:: numpy.doc.misc .. automodule:: numpy.doc.methods_vs_functions diff --git a/doc/source/user/performance.rst b/doc/source/user/performance.rst index 1f6e4e16c..59f8a2edc 100644 --- a/doc/source/user/performance.rst +++ b/doc/source/user/performance.rst @@ -2,6 +2,4 @@ Performance *********** -.. note:: XXX: This section is not yet written. - .. automodule:: numpy.doc.performance -- cgit v1.2.1