DOC: Rearrange the polynomial documents.

This is the first step in cleaning up the polynomial documentation
and writing an instructional section on the convenience classes.

10 files changed, 623 insertions, 47 deletions

diff --git a/doc/source/reference/routines.polynomials.chebyshev.rst b/doc/source/reference/routines.polynomials.chebyshev.rst
new file mode 100644
index 000000000..dae74ce6b
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.chebyshev.rst
@@ -0,0 +1,90 @@
+Chebyshev Module (:mod:`numpy.polynomial.chebyshev`)
+====================================================
+
+.. currentmodule:: numpy.polynomial.chebyshev
+
+This module provides a number of objects (mostly functions) useful for
+dealing with Chebyshev series, including a `Chebyshev` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+Chebyshev Class
+---------------
+.. autosummary::
+   :toctree: generated/
+
+   .. _chebyshev-class:
+   Chebyshev
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebval
+   chebval2d
+   chebval3d
+   chebgrid2d
+   chebgrid3d
+   chebroots
+   chebfromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebfit
+   chebvander
+   chebvander2d
+   chebvander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebder
+   chebint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebadd
+   chebsub
+   chebmul
+   chebmulx
+   chebdiv
+   chebpow
+
+Quadrature
+----------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebgauss
+   chebweight
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   chebcompanion
+   chebdomain
+   chebzero
+   chebone
+   chebx
+   chebtrim
+   chebline
+   cheb2poly
+   poly2cheb
diff --git a/doc/source/reference/routines.polynomials.classes.rst b/doc/source/reference/routines.polynomials.classes.rst
new file mode 100644
index 000000000..803251fbf
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.classes.rst
@@ -0,0 +1,15 @@
+Using the Convenience Classes
+=============================
+
+The classes in the polynomial package can be imported directly from
+numpy.polynomial as well as from the corresponding modules.::
+
+    >>> from numpy.polynomial import Polynomial as P
+    >>> p = P([0, 0, 1])
+    >>> p**2
+    Polynomial([ 0.,  0.,  0.,  0.,  1.], [-1.,  1.], [-1.,  1.])
+
+Because most of the functionality in the modules of the polynomial package
+is available through the corresponding classes, including fitting, shifting
+and scaling, and conversion between classes, it should not be necessary to
+use the functions in the modules except for multi-dimensional work.
diff --git a/doc/source/reference/routines.polynomials.hermite.rst b/doc/source/reference/routines.polynomials.hermite.rst
new file mode 100644
index 000000000..0600b3ea6
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.hermite.rst
@@ -0,0 +1,90 @@
+Hermite Module (:mod:`numpy.polynomial.hermite`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: numpy.polynomial.hermite
+
+This module provides a number of objects (mostly functions) useful for
+dealing with Hermite series, including a `Hermite` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+Hermite Class
+-------------
+.. autosummary::
+   :toctree: generated/
+
+   .. _hermite-class:
+   Hermite
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermval
+   hermval2d
+   hermval3d
+   hermgrid2d
+   hermgrid3d
+   hermroots
+   hermfromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermfit
+   hermvander
+   hermvander2d
+   hermvander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermder
+   hermint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermadd
+   hermsub
+   hermmul
+   hermmulx
+   hermdiv
+   hermpow
+
+Quadrature
+----------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermgauss
+   hermweight
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermcompanion
+   hermdomain
+   hermzero
+   hermone
+   hermx
+   hermtrim
+   hermline
+   herm2poly
+   poly2herm
diff --git a/doc/source/reference/routines.polynomials.hermite_e.rst b/doc/source/reference/routines.polynomials.hermite_e.rst
new file mode 100644
index 000000000..02ef731c6
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.hermite_e.rst
@@ -0,0 +1,91 @@
+HermiteE Module (:mod:`numpy.polynomial.hermite_e`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: numpy.polynomial.hermite_e
+
+This module provides a number of objects (mostly functions) useful for
+dealing with HermiteE series, including a `HermiteE` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+.. _hermite_e:
+
+HermiteE Class
+--------------
+.. autosummary::
+   :toctree: generated/
+
+   HermiteE
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermeval
+   hermeval2d
+   hermeval3d
+   hermegrid2d
+   hermegrid3d
+   hermeroots
+   hermefromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermefit
+   hermevander
+   hermevander2d
+   hermevander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermeder
+   hermeint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermeadd
+   hermesub
+   hermemul
+   hermemulx
+   hermediv
+   hermepow
+
+Quadrature
+----------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermegauss
+   hermeweight
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   hermecompanion
+   hermedomain
+   hermezero
+   hermeone
+   hermex
+   hermetrim
+   hermeline
+   herme2poly
+   poly2herme
diff --git a/doc/source/reference/routines.polynomials.laguerre.rst b/doc/source/reference/routines.polynomials.laguerre.rst
new file mode 100644
index 000000000..daa59076a
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.laguerre.rst
@@ -0,0 +1,90 @@
+Laguerre Module (:mod:`numpy.polynomial.laguerre`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: numpy.polynomial.laguerre
+
+This module provides a number of objects (mostly functions) useful for
+dealing with Laguerre series, including a `Laguerre` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+Laguerre Class
+--------------
+.. autosummary::
+   :toctree: generated/
+
+   .. _laguerre-class:
+   Laguerre
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   lagval
+   lagval2d
+   lagval3d
+   laggrid2d
+   laggrid3d
+   lagroots
+   lagfromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   lagfit
+   lagvander
+   lagvander2d
+   lagvander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   lagder
+   lagint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   lagadd
+   lagsub
+   lagmul
+   lagmulx
+   lagdiv
+   lagpow
+
+Quadrature
+----------
+
+.. autosummary::
+   :toctree: generated/
+
+   laggauss
+   lagweight
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   lagcompanion
+   lagdomain
+   lagzero
+   lagone
+   lagx
+   lagtrim
+   lagline
+   lag2poly
+   poly2lag
diff --git a/doc/source/reference/routines.polynomials.legendre.rst b/doc/source/reference/routines.polynomials.legendre.rst
new file mode 100644
index 000000000..e329ba740
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.legendre.rst
@@ -0,0 +1,90 @@
+Legendre Module (:mod:`numpy.polynomial.legendre`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: numpy.polynomial.legendre
+
+This module provides a number of objects (mostly functions) useful for
+dealing with Legendre series, including a `Legendre` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+Legendre Class
+--------------
+.. autosummary::
+   :toctree: generated/
+
+   .. _legendre-class:
+   Legendre
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   legval
+   legval2d
+   legval3d
+   leggrid2d
+   leggrid3d
+   legroots
+   legfromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   legfit
+   legvander
+   legvander2d
+   legvander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   legder
+   legint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   legadd
+   legsub
+   legmul
+   legmulx
+   legdiv
+   legpow
+
+Quadrature
+----------
+
+.. autosummary::
+   :toctree: generated/
+
+   leggauss
+   legweight
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   legcompanion
+   legdomain
+   legzero
+   legone
+   legx
+   legtrim
+   legline
+   leg2poly
+   poly2leg
diff --git a/doc/source/reference/routines.polynomials.package.rst b/doc/source/reference/routines.polynomials.package.rst
new file mode 100644
index 000000000..557e4ba33
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.package.rst
@@ -0,0 +1,15 @@
+Polynomial Package
+==================
+
+.. currentmodule:: numpy.polynomial
+
+.. toctree::
+   :maxdepth: 2
+
+   routines.polynomials.classes
+   routines.polynomials.polynomial
+   routines.polynomials.chebyshev
+   routines.polynomials.legendre
+   routines.polynomials.laguerre
+   routines.polynomials.hermite
+   routines.polynomials.hermite_e
diff --git a/doc/source/reference/routines.polynomials.polynomial.rst b/doc/source/reference/routines.polynomials.polynomial.rst
index aa92ce8fc..d555a1145 100644
--- a/doc/source/reference/routines.polynomials.polynomial.rst
+++ b/doc/source/reference/routines.polynomials.polynomial.rst
@@ -1,16 +1,79 @@
-Polynomial Package (:mod:`numpy.polynomial`)
-============================================
+Polynomial Module (:mod:`numpy.polynomial.polynomial`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. currentmodule:: numpy.polynomial
+.. currentmodule:: numpy.polynomial.polynomial
 
-Polynomial Classes
-------------------
+This module provides a number of objects (mostly functions) useful for
+dealing with Polynomial series, including a `Polynomial` class that
+encapsulates the usual arithmetic operations.  (General information
+on how this module represents and works with such polynomials is in the
+docstring for its "parent" sub-package, `numpy.polynomial`).
+
+Polynomial Class
+----------------
 .. autosummary::
    :toctree: generated/
 
+   .. _polynomial-class:
    Polynomial
-   Chebyshev
-   Legendre
-   Hermite
-   HermiteE
-   Laguerre
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   polyval
+   polyval2d
+   polyval3d
+   polygrid2d
+   polygrid3d
+   polyroots
+   polyfromroots
+
+Fitting
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   polyfit
+   polyvander
+   polyvander2d
+   polyvander3d
+
+Calculus
+--------
+
+.. autosummary::
+   :toctree: generated/
+
+   polyder
+   polyint
+
+Algebra
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   polyadd
+   polysub
+   polymul
+   polymulx
+   polydiv
+   polypow
+
+Miscellaneous
+-------------
+
+.. autosummary::
+   :toctree: generated/
+
+   polycompanion
+   polydomain
+   polyzero
+   polyone
+   polyx
+   polytrim
+   polyline
diff --git a/doc/source/reference/routines.polynomials.rst b/doc/source/reference/routines.polynomials.rst
index 59d6bc499..94d1af8e7 100644
--- a/doc/source/reference/routines.polynomials.rst
+++ b/doc/source/reference/routines.polynomials.rst
@@ -1,14 +1,23 @@
 Polynomials
 ***********
 
-The poly1d functions are considered outdated but are retained for
-backward compatibility. New software needing polynomials should
-use the classes in the Polynomial Package.
+The polynomial package is newer and more complete than poly1d and the
+convenience classes are better behaved in the numpy environment. When
+backwards compatibility is not an issue it should be the package of choice.
+Note that the  various routines in the polynomial package all deal with
+series whose coefficients go from degree zero upward, which is the reverse
+of the poly1d convention. The easy way to remember this is that indexes
+correspond to degree, i.e., coef[i] is the coefficient of the term of
+degree i.
+
 
 .. toctree::
    :maxdepth: 2
 
-   routines.polynomials.polynomial
    routines.polynomials.poly1d
 
 
+.. toctree::
+   :maxdepth: 3
+
+   routines.polynomials.package
diff --git a/numpy/polynomial/legendre.py b/numpy/polynomial/legendre.py
index 93ba1d348..f084617b6 100644
--- a/numpy/polynomial/legendre.py
+++ b/numpy/polynomial/legendre.py
@@ -1,5 +1,8 @@
 """
-Objects for dealing with Legendre series.
+Legendre Series (:mod: `numpy.polynomial.legendre`)
+===================================================
+
+.. currentmodule:: numpy.polynomial.polynomial
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Legendre series, including a `Legendre` class that
@@ -9,53 +12,73 @@ docstring for its "parent" sub-package, `numpy.polynomial`).
 
 Constants
 ---------
-- `legdomain` -- Legendre series default domain, [-1,1].
-- `legzero` -- Legendre series that evaluates identically to 0.
-- `legone` -- Legendre series that evaluates identically to 1.
-- `legx` -- Legendre series for the identity map, ``f(x) = x``.
+
+.. autosummary::
+   :toctree: generated/
+
+   legdomain            Legendre series default domain, [-1,1].
+   legzero              Legendre series that evaluates identically to 0.
+   legone               Legendre series that evaluates identically to 1.
+   legx                 Legendre series for the identity map, ``f(x) = x``.
 
 Arithmetic
 ----------
-- `legmulx` -- multiply a Legendre series in ``P_i(x)`` by ``x``.
-- `legadd` -- add two Legendre series.
-- `legsub` -- subtract one Legendre series from another.
-- `legmul` -- multiply two Legendre series.
-- `legdiv` -- divide one Legendre series by another.
-- `legpow` -- raise a Legendre series to an positive integer power
-- `legval` -- evaluate a Legendre series at given points.
-- `legval2d` -- evaluate a 2D Legendre series at given points.
-- `legval3d` -- evaluate a 3D Legendre series at given points.
-- `leggrid2d` -- evaluate a 2D Legendre series on a Cartesian product.
-- `leggrid3d` -- evaluate a 3D Legendre series on a Cartesian product.
+
+.. autosummary::
+   :toctree: generated/
+
+   legmulx              multiply a Legendre series in P_i(x) by x.
+   legadd               add two Legendre series.
+   legsub               subtract one Legendre series from another.
+   legmul               multiply two Legendre series.
+   legdiv               divide one Legendre series by another.
+   legpow               raise a Legendre series to an positive integer power
+   legval               evaluate a Legendre series at given points.
+   legval2d             evaluate a 2D Legendre series at given points.
+   legval3d             evaluate a 3D Legendre series at given points.
+   leggrid2d            evaluate a 2D Legendre series on a Cartesian product.
+   leggrid3d            evaluate a 3D Legendre series on a Cartesian product.
 
 Calculus
 --------
-- `legder` -- differentiate a Legendre series.
-- `legint` -- integrate a Legendre series.
+
+.. autosummary::
+   :toctree: generated/
+
+   legder               differentiate a Legendre series.
+   legint               integrate a Legendre series.
 
 Misc Functions
 --------------
-- `legfromroots` -- create a Legendre series with specified roots.
-- `legroots` -- find the roots of a Legendre series.
-- `legvander` -- Vandermonde-like matrix for Legendre polynomials.
-- `legvander2d` -- Vandermonde-like matrix for 2D power series.
-- `legvander3d` -- Vandermonde-like matrix for 3D power series.
-- `leggauss` -- Gauss-Legendre quadrature, points and weights.
-- `legweight` -- Legendre weight function.
-- `legcompanion` -- symmetrized companion matrix in Legendre form.
-- `legfit` -- least-squares fit returning a Legendre series.
-- `legtrim` -- trim leading coefficients from a Legendre series.
-- `legline` -- Legendre series representing given straight line.
-- `leg2poly` -- convert a Legendre series to a polynomial.
-- `poly2leg` -- convert a polynomial to a Legendre series.
+
+.. autosummary::
+   :toctree: generated/
+
+   legfromroots          create a Legendre series with specified roots.
+   legroots              find the roots of a Legendre series.
+   legvander             Vandermonde-like matrix for Legendre polynomials.
+   legvander2d           Vandermonde-like matrix for 2D power series.
+   legvander3d           Vandermonde-like matrix for 3D power series.
+   leggauss              Gauss-Legendre quadrature, points and weights.
+   legweight             Legendre weight function.
+   legcompanion          symmetrized companion matrix in Legendre form.
+   legfit                least-squares fit returning a Legendre series.
+   legtrim               trim leading coefficients from a Legendre series.
+   legline               Legendre series representing given straight line.
+   leg2poly              convert a Legendre series to a polynomial.
+   poly2leg              convert a polynomial to a Legendre series.
 
 Classes
 -------
-- `Legendre` -- A Legendre series class.
+    Legendre            A Legendre series class.
 
 See also
 --------
-`numpy.polynomial`
+numpy.polynomial.polynomial
+numpy.polynomial.chebyshev
+numpy.polynomial.laguerre
+numpy.polynomial.hermite
+numpy.polynomial.hermite_e
 
 """
 from __future__ import division