[SciPy-dev] NumPy User Guide table of contents

[Pauli Virtanen]

Hi all,

It's great to see that people are interested in contributing
narrative documentation to Numpy! I think this effort will be
accelerated much if we have a table of contents for the final
manual we want, to guide the writing.

One suggestion is listed below. It's also on this wiki page:

	http://scipy.org/Developer_Zone/UG_Toc

It's not complete or final, but should already serve at least
as a starting point. I think it would be best if we agreed on
this first, fleshing out what should go where, and what each
chapter should contain, before spending too much time on
writing actual content.

So, please chip in: look at the suggestion below, and criticize
it and fill in additions and ideas.

Cheers,
Pauli

    ***

************
Numpy Manual
************

The aim here is to write narrative documentation that illustrates how
Numpy is best used in practice, demonstrating various features it
offers, with examples and enlightened discussion.

Below, a draft for the table of contents is listed. It is formed by
looking at

- `Numeric manual <http://numpy.scipy.org/numpydoc/numdoc.htm>`__
- `Guide to Numpy <http://www.tramy.us/>`__

and stealing whatever seemed good to include. It's a rough draft, and
probably needs tuning at various points. Also, I'm aware not all of
Numpy is there now, so additions should also be made.


#. Introduction to Numpy
   #. What it is
   #. What is there: a very high-level overview
   #. Conventions in this manual
#. Installing Numpy
   #. Instructions for getting binaries
   #. Instructions for building from source, on different platforms
#. Basics of arrays
  #. What is an array
  #. Storing data in arrays
     #. Arrays as literals
     #. Creating arrays: empty, zeros, ones, ...
     #. Saving/loading to a file: text, npz  -> point to other IO routines
  #. Extracting data from arrays
     #. Basic indexing and slicing
     #. Simple fancy indexing
     #. Finding items in arrays
        #. comparisons, logic operations, indexing based on them
        #. where, searchsorted
     #. Advanced indexing on arrays: ellipsis, newaxis
  #. Views and copies of arrays
     #. Demonstrate that slicing in general creates views
  #. Modifying contents of arrays
     #. Setting data in arrays via indexing
     #. add, multiply subtract
     #. in-place operations (+ the common indexing caveat!)
     #. sum, mean, min, max, ...
     #. remark on ufuncs: common methods
     #. Operating on an axis of an array
  #. Broadcasting
  #. Joining, splitting arrays and changing their shape
     #. *stack, *split
     #. reshape
     #. resize
  #. Working with different types of data: integers, floats, complex, strings...
     #. Basic creation of arrays with certain data types
     #. Building up data type objects
     #. Casting and converting array data, automatic casting, coercion
  #. Advanced data types and structured arrays
     #. Creating structured arrays
     #. Defining them: literals, loading from files
     #. Accessing data in them
#. Other topics
   #. Working with missing data
      #. NaNs as masking
      #. Masked arrays
   #. Linear algebra and matrices
   #. Working with polynomials
   #. Floating point issues: errors, error handling, inaccuracy, etc.
   #. Fourier transforms
   #. Generating random numbers
   #. Building and testing packages using Numpy
   #. Financial calculations with Numpy
#. Extending Numpy
   #. Subclassing numpy arrays
   #. Array interface
   #. Ctypes support in Numpy
   #. Cython? Pyrex? F2Py?
   #. Writing C extensions using Numpy
      #. Basics
      #. Iteration
      #. Ufuncs
      #. Data types
      #. Subclassing in C
#. Numpy internals
   #. Memory model
   #. Data type stuff
   #. Ufuncs
   #. etc?

#. Reference
   <insert our current "reference manual" here as-is and factor out
   any duplication later on>