DOC: Refactor `np.polynomial` docs using `automodule` (#15662)

* DOC: Refactor polynomial docs using automodule.

6 files changed, 306 insertions, 220 deletions

diff --git a/numpy/polynomial/chebyshev.py b/numpy/polynomial/chebyshev.py
index e547d151c..1329ba07d 100644
--- a/numpy/polynomial/chebyshev.py
+++ b/numpy/polynomial/chebyshev.py
@@ -1,5 +1,7 @@
 """
-Objects for dealing with Chebyshev series.
+====================================================
+Chebyshev Series (:mod:`numpy.polynomial.chebyshev`)
+====================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Chebyshev series, including a `Chebyshev` class that
@@ -7,57 +9,75 @@ 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`).
 
+Classes
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   Chebyshev
+
+
 Constants
 ---------
-- `chebdomain` -- Chebyshev series default domain, [-1,1].
-- `chebzero` -- (Coefficients of the) Chebyshev series that evaluates
-  identically to 0.
-- `chebone` -- (Coefficients of the) Chebyshev series that evaluates
-  identically to 1.
-- `chebx` -- (Coefficients of the) Chebyshev series for the identity map,
-  ``f(x) = x``.
+
+.. autosummary::
+   :toctree: generated/
+
+   chebdomain
+   chebzero
+   chebone
+   chebx
 
 Arithmetic
 ----------
-- `chebadd` -- add two Chebyshev series.
-- `chebsub` -- subtract one Chebyshev series from another.
-- `chebmulx` -- multiply a Chebyshev series in ``P_i(x)`` by ``x``.
-- `chebmul` -- multiply two Chebyshev series.
-- `chebdiv` -- divide one Chebyshev series by another.
-- `chebpow` -- raise a Chebyshev series to a positive integer power.
-- `chebval` -- evaluate a Chebyshev series at given points.
-- `chebval2d` -- evaluate a 2D Chebyshev series at given points.
-- `chebval3d` -- evaluate a 3D Chebyshev series at given points.
-- `chebgrid2d` -- evaluate a 2D Chebyshev series on a Cartesian product.
-- `chebgrid3d` -- evaluate a 3D Chebyshev series on a Cartesian product.
+
+.. autosummary::
+   :toctree: generated/
+
+   chebadd
+   chebsub
+   chebmulx
+   chebmul
+   chebdiv
+   chebpow
+   chebval
+   chebval2d
+   chebval3d
+   chebgrid2d
+   chebgrid3d
 
 Calculus
 --------
-- `chebder` -- differentiate a Chebyshev series.
-- `chebint` -- integrate a Chebyshev series.
+
+.. autosummary::
+   :toctree: generated/
+
+   chebder
+   chebint
 
 Misc Functions
 --------------
-- `chebfromroots` -- create a Chebyshev series with specified roots.
-- `chebroots` -- find the roots of a Chebyshev series.
-- `chebvander` -- Vandermonde-like matrix for Chebyshev polynomials.
-- `chebvander2d` -- Vandermonde-like matrix for 2D power series.
-- `chebvander3d` -- Vandermonde-like matrix for 3D power series.
-- `chebgauss` -- Gauss-Chebyshev quadrature, points and weights.
-- `chebweight` -- Chebyshev weight function.
-- `chebcompanion` -- symmetrized companion matrix in Chebyshev form.
-- `chebfit` -- least-squares fit returning a Chebyshev series.
-- `chebpts1` -- Chebyshev points of the first kind.
-- `chebpts2` -- Chebyshev points of the second kind.
-- `chebtrim` -- trim leading coefficients from a Chebyshev series.
-- `chebline` -- Chebyshev series representing given straight line.
-- `cheb2poly` -- convert a Chebyshev series to a polynomial.
-- `poly2cheb` -- convert a polynomial to a Chebyshev series.
-- `chebinterpolate` -- interpolate a function at the Chebyshev points.
 
-Classes
--------
-- `Chebyshev` -- A Chebyshev series class.
+.. autosummary::
+   :toctree: generated/
+
+   chebfromroots
+   chebroots
+   chebvander
+   chebvander2d
+   chebvander3d
+   chebgauss
+   chebweight
+   chebcompanion
+   chebfit
+   chebpts1
+   chebpts2
+   chebtrim
+   chebline
+   cheb2poly
+   poly2cheb
+   chebinterpolate
 
 See also
 --------
diff --git a/numpy/polynomial/hermite.py b/numpy/polynomial/hermite.py
index 4db344720..44b26f5ee 100644
--- a/numpy/polynomial/hermite.py
+++ b/numpy/polynomial/hermite.py
@@ -1,5 +1,7 @@
 """
-Objects for dealing with Hermite series.
+==============================================================
+Hermite Series, "Physicists" (:mod:`numpy.polynomial.hermite`)
+==============================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Hermite series, including a `Hermite` class that
@@ -7,51 +9,66 @@ 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`).
 
+Classes
+-------
+.. autosummary::
+   :toctree: generated/
+
+   Hermite
+
 Constants
 ---------
-- `hermdomain` -- Hermite series default domain, [-1,1].
-- `hermzero` -- Hermite series that evaluates identically to 0.
-- `hermone` -- Hermite series that evaluates identically to 1.
-- `hermx` -- Hermite series for the identity map, ``f(x) = x``.
+.. autosummary::
+   :toctree: generated/
+
+   hermdomain
+   hermzero
+   hermone
+   hermx
 
 Arithmetic
 ----------
-- `hermadd` -- add two Hermite series.
-- `hermsub` -- subtract one Hermite series from another.
-- `hermmulx` -- multiply a Hermite series in ``P_i(x)`` by ``x``.
-- `hermmul` -- multiply two Hermite series.
-- `hermdiv` -- divide one Hermite series by another.
-- `hermpow` -- raise a Hermite series to a positive integer power.
-- `hermval` -- evaluate a Hermite series at given points.
-- `hermval2d` -- evaluate a 2D Hermite series at given points.
-- `hermval3d` -- evaluate a 3D Hermite series at given points.
-- `hermgrid2d` -- evaluate a 2D Hermite series on a Cartesian product.
-- `hermgrid3d` -- evaluate a 3D Hermite series on a Cartesian product.
+.. autosummary::
+   :toctree: generated/
+
+   hermadd
+   hermsub
+   hermmulx
+   hermmul
+   hermdiv
+   hermpow
+   hermval
+   hermval2d
+   hermval3d
+   hermgrid2d
+   hermgrid3d
 
 Calculus
 --------
-- `hermder` -- differentiate a Hermite series.
-- `hermint` -- integrate a Hermite series.
+.. autosummary::
+   :toctree: generated/
+
+   hermder
+   hermint
 
 Misc Functions
 --------------
-- `hermfromroots` -- create a Hermite series with specified roots.
-- `hermroots` -- find the roots of a Hermite series.
-- `hermvander` -- Vandermonde-like matrix for Hermite polynomials.
-- `hermvander2d` -- Vandermonde-like matrix for 2D power series.
-- `hermvander3d` -- Vandermonde-like matrix for 3D power series.
-- `hermgauss` -- Gauss-Hermite quadrature, points and weights.
-- `hermweight` -- Hermite weight function.
-- `hermcompanion` -- symmetrized companion matrix in Hermite form.
-- `hermfit` -- least-squares fit returning a Hermite series.
-- `hermtrim` -- trim leading coefficients from a Hermite series.
-- `hermline` -- Hermite series of given straight line.
-- `herm2poly` -- convert a Hermite series to a polynomial.
-- `poly2herm` -- convert a polynomial to a Hermite series.
-
-Classes
--------
-- `Hermite` -- A Hermite series class.
+.. autosummary::
+   :toctree: generated/
+
+   hermfromroots
+   hermroots
+   hermvander
+   hermvander2d
+   hermvander3d
+   hermgauss
+   hermweight
+   hermcompanion
+   hermfit
+   hermtrim
+   hermline
+   herm2poly
+   poly2herm
 
 See also
 --------
diff --git a/numpy/polynomial/hermite_e.py b/numpy/polynomial/hermite_e.py
index a7ff67f9c..1a18843ec 100644
--- a/numpy/polynomial/hermite_e.py
+++ b/numpy/polynomial/hermite_e.py
@@ -1,5 +1,7 @@
 """
-Objects for dealing with Hermite_e series.
+===================================================================
+HermiteE Series, "Probabilists" (:mod:`numpy.polynomial.hermite_e`)
+===================================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Hermite_e series, including a `HermiteE` class that
@@ -7,51 +9,66 @@ 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`).
 
+Classes
+-------
+.. autosummary::
+   :toctree: generated/
+
+   HermiteE
+
 Constants
 ---------
-- `hermedomain` -- Hermite_e series default domain, [-1,1].
-- `hermezero` -- Hermite_e series that evaluates identically to 0.
-- `hermeone` -- Hermite_e series that evaluates identically to 1.
-- `hermex` -- Hermite_e series for the identity map, ``f(x) = x``.
+.. autosummary::
+   :toctree: generated/
+
+   hermedomain
+   hermezero
+   hermeone
+   hermex
 
 Arithmetic
 ----------
-- `hermeadd` -- add two Hermite_e series.
-- `hermesub` -- subtract one Hermite_e series from another.
-- `hermemulx` -- multiply a Hermite_e series in ``P_i(x)`` by ``x``.
-- `hermemul` -- multiply two Hermite_e series.
-- `hermediv` -- divide one Hermite_e series by another.
-- `hermepow` -- raise a Hermite_e series to a positive integer power.
-- `hermeval` -- evaluate a Hermite_e series at given points.
-- `hermeval2d` -- evaluate a 2D Hermite_e series at given points.
-- `hermeval3d` -- evaluate a 3D Hermite_e series at given points.
-- `hermegrid2d` -- evaluate a 2D Hermite_e series on a Cartesian product.
-- `hermegrid3d` -- evaluate a 3D Hermite_e series on a Cartesian product.
+.. autosummary::
+   :toctree: generated/
+
+   hermeadd
+   hermesub
+   hermemulx
+   hermemul
+   hermediv
+   hermepow
+   hermeval
+   hermeval2d
+   hermeval3d
+   hermegrid2d
+   hermegrid3d
 
 Calculus
 --------
-- `hermeder` -- differentiate a Hermite_e series.
-- `hermeint` -- integrate a Hermite_e series.
+.. autosummary::
+   :toctree: generated/
+
+   hermeder
+   hermeint
 
 Misc Functions
 --------------
-- `hermefromroots` -- create a Hermite_e series with specified roots.
-- `hermeroots` -- find the roots of a Hermite_e series.
-- `hermevander` -- Vandermonde-like matrix for Hermite_e polynomials.
-- `hermevander2d` -- Vandermonde-like matrix for 2D power series.
-- `hermevander3d` -- Vandermonde-like matrix for 3D power series.
-- `hermegauss` -- Gauss-Hermite_e quadrature, points and weights.
-- `hermeweight` -- Hermite_e weight function.
-- `hermecompanion` -- symmetrized companion matrix in Hermite_e form.
-- `hermefit` -- least-squares fit returning a Hermite_e series.
-- `hermetrim` -- trim leading coefficients from a Hermite_e series.
-- `hermeline` -- Hermite_e series of given straight line.
-- `herme2poly` -- convert a Hermite_e series to a polynomial.
-- `poly2herme` -- convert a polynomial to a Hermite_e series.
-
-Classes
--------
-- `HermiteE` -- A Hermite_e series class.
+.. autosummary::
+   :toctree: generated/
+
+   hermefromroots
+   hermeroots
+   hermevander
+   hermevander2d
+   hermevander3d
+   hermegauss
+   hermeweight
+   hermecompanion
+   hermefit
+   hermetrim
+   hermeline
+   herme2poly
+   poly2herme
 
 See also
 --------
diff --git a/numpy/polynomial/laguerre.py b/numpy/polynomial/laguerre.py
index 0ab17f2f1..89bb8e168 100644
--- a/numpy/polynomial/laguerre.py
+++ b/numpy/polynomial/laguerre.py
@@ -1,5 +1,7 @@
 """
-Objects for dealing with Laguerre series.
+==================================================
+Laguerre Series (:mod:`numpy.polynomial.laguerre`)
+==================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Laguerre series, including a `Laguerre` class that
@@ -7,51 +9,66 @@ 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`).
 
+Classes
+-------
+.. autosummary::
+   :toctree: generated/
+
+   Laguerre
+
 Constants
 ---------
-- `lagdomain` -- Laguerre series default domain, [-1,1].
-- `lagzero` -- Laguerre series that evaluates identically to 0.
-- `lagone` -- Laguerre series that evaluates identically to 1.
-- `lagx` -- Laguerre series for the identity map, ``f(x) = x``.
+.. autosummary::
+   :toctree: generated/
+
+   lagdomain
+   lagzero
+   lagone
+   lagx
 
 Arithmetic
 ----------
-- `lagadd` -- add two Laguerre series.
-- `lagsub` -- subtract one Laguerre series from another.
-- `lagmulx` -- multiply a Laguerre series in ``P_i(x)`` by ``x``.
-- `lagmul` -- multiply two Laguerre series.
-- `lagdiv` -- divide one Laguerre series by another.
-- `lagpow` -- raise a Laguerre series to a positive integer power.
-- `lagval` -- evaluate a Laguerre series at given points.
-- `lagval2d` -- evaluate a 2D Laguerre series at given points.
-- `lagval3d` -- evaluate a 3D Laguerre series at given points.
-- `laggrid2d` -- evaluate a 2D Laguerre series on a Cartesian product.
-- `laggrid3d` -- evaluate a 3D Laguerre series on a Cartesian product.
+.. autosummary::
+   :toctree: generated/
+
+   lagadd
+   lagsub
+   lagmulx
+   lagmul
+   lagdiv
+   lagpow
+   lagval
+   lagval2d
+   lagval3d
+   laggrid2d
+   laggrid3d
 
 Calculus
 --------
-- `lagder` -- differentiate a Laguerre series.
-- `lagint` -- integrate a Laguerre series.
+.. autosummary::
+   :toctree: generated/
+
+   lagder
+   lagint
 
 Misc Functions
 --------------
-- `lagfromroots` -- create a Laguerre series with specified roots.
-- `lagroots` -- find the roots of a Laguerre series.
-- `lagvander` -- Vandermonde-like matrix for Laguerre polynomials.
-- `lagvander2d` -- Vandermonde-like matrix for 2D power series.
-- `lagvander3d` -- Vandermonde-like matrix for 3D power series.
-- `laggauss` -- Gauss-Laguerre quadrature, points and weights.
-- `lagweight` -- Laguerre weight function.
-- `lagcompanion` -- symmetrized companion matrix in Laguerre form.
-- `lagfit` -- least-squares fit returning a Laguerre series.
-- `lagtrim` -- trim leading coefficients from a Laguerre series.
-- `lagline` -- Laguerre series of given straight line.
-- `lag2poly` -- convert a Laguerre series to a polynomial.
-- `poly2lag` -- convert a polynomial to a Laguerre series.
-
-Classes
--------
-- `Laguerre` -- A Laguerre series class.
+.. autosummary::
+   :toctree: generated/
+
+   lagfromroots
+   lagroots
+   lagvander
+   lagvander2d
+   lagvander3d
+   laggauss
+   lagweight
+   lagcompanion
+   lagfit
+   lagtrim
+   lagline
+   lag2poly
+   poly2lag
 
 See also
 --------
diff --git a/numpy/polynomial/legendre.py b/numpy/polynomial/legendre.py
index ec2f9e828..85fd5b18b 100644
--- a/numpy/polynomial/legendre.py
+++ b/numpy/polynomial/legendre.py
@@ -1,8 +1,7 @@
 """
-Legendre Series (:mod: `numpy.polynomial.legendre`)
-===================================================
-
-.. currentmodule:: numpy.polynomial.polynomial
+==================================================
+Legendre Series (:mod:`numpy.polynomial.legendre`)
+==================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with Legendre series, including a `Legendre` class that
@@ -10,16 +9,23 @@ 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`).
 
+Classes
+-------
+.. autosummary::
+   :toctree: generated/
+
+    Legendre
+
 Constants
 ---------
 
 .. 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``.
+   legdomain
+   legzero
+   legone
+   legx
 
 Arithmetic
 ----------
@@ -27,17 +33,17 @@ Arithmetic
 .. autosummary::
    :toctree: generated/
 
-   legadd               add two Legendre series.
-   legsub               subtract one Legendre series from another.
-   legmulx              multiply a Legendre series in ``P_i(x)`` by ``x``.
-   legmul               multiply two Legendre series.
-   legdiv               divide one Legendre series by another.
-   legpow               raise a Legendre series to a 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.
+   legadd
+   legsub
+   legmulx
+   legmul
+   legdiv
+   legpow
+   legval
+   legval2d
+   legval3d
+   leggrid2d
+   leggrid3d
 
 Calculus
 --------
@@ -45,8 +51,8 @@ Calculus
 .. autosummary::
    :toctree: generated/
 
-   legder               differentiate a Legendre series.
-   legint               integrate a Legendre series.
+   legder
+   legint
 
 Misc Functions
 --------------
@@ -54,31 +60,23 @@ Misc Functions
 .. 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.
+   legfromroots
+   legroots
+   legvander
+   legvander2d
+   legvander3d
+   leggauss
+   legweight
+   legcompanion
+   legfit
+   legtrim
+   legline
+   leg2poly
+   poly2leg
 
 See also
 --------
-numpy.polynomial.polynomial
-numpy.polynomial.chebyshev
-numpy.polynomial.laguerre
-numpy.polynomial.hermite
-numpy.polynomial.hermite_e
+numpy.polynomial
 
 """
 import numpy as np
diff --git a/numpy/polynomial/polynomial.py b/numpy/polynomial/polynomial.py
index 97f66a152..2fb032db3 100644
--- a/numpy/polynomial/polynomial.py
+++ b/numpy/polynomial/polynomial.py
@@ -1,5 +1,7 @@
 """
-Objects for dealing with polynomials.
+=================================================
+Power Series (:mod:`numpy.polynomial.polynomial`)
+=================================================
 
 This module provides a number of objects (mostly functions) useful for
 dealing with polynomials, including a `Polynomial` class that
@@ -7,48 +9,63 @@ encapsulates the usual arithmetic operations.  (General information
 on how this module represents and works with polynomial objects is in
 the docstring for its "parent" sub-package, `numpy.polynomial`).
 
+Classes
+-------
+.. autosummary::
+   :toctree: generated/
+
+   Polynomial
+
 Constants
 ---------
-- `polydomain` -- Polynomial default domain, [-1,1].
-- `polyzero` -- (Coefficients of the) "zero polynomial."
-- `polyone` -- (Coefficients of the) constant polynomial 1.
-- `polyx` -- (Coefficients of the) identity map polynomial, ``f(x) = x``.
+.. autosummary::
+   :toctree: generated/
+
+   polydomain
+   polyzero
+   polyone
+   polyx
 
 Arithmetic
 ----------
-- `polyadd` -- add two polynomials.
-- `polysub` -- subtract one polynomial from another.
-- `polymulx` -- multiply a polynomial in ``P_i(x)`` by ``x``.
-- `polymul` -- multiply two polynomials.
-- `polydiv` -- divide one polynomial by another.
-- `polypow` -- raise a polynomial to a positive integer power.
-- `polyval` -- evaluate a polynomial at given points.
-- `polyval2d` -- evaluate a 2D polynomial at given points.
-- `polyval3d` -- evaluate a 3D polynomial at given points.
-- `polygrid2d` -- evaluate a 2D polynomial on a Cartesian product.
-- `polygrid3d` -- evaluate a 3D polynomial on a Cartesian product.
+.. autosummary::
+   :toctree: generated/
+
+   polyadd
+   polysub
+   polymulx
+   polymul
+   polydiv
+   polypow
+   polyval
+   polyval2d
+   polyval3d
+   polygrid2d
+   polygrid3d
 
 Calculus
 --------
-- `polyder` -- differentiate a polynomial.
-- `polyint` -- integrate a polynomial.
+.. autosummary::
+   :toctree: generated/
+
+   polyder
+   polyint
 
 Misc Functions
 --------------
-- `polyfromroots` -- create a polynomial with specified roots.
-- `polyroots` -- find the roots of a polynomial.
-- `polyvalfromroots` -- evaluate a polynomial at given points from roots.
-- `polyvander` -- Vandermonde-like matrix for powers.
-- `polyvander2d` -- Vandermonde-like matrix for 2D power series.
-- `polyvander3d` -- Vandermonde-like matrix for 3D power series.
-- `polycompanion` -- companion matrix in power series form.
-- `polyfit` -- least-squares fit returning a polynomial.
-- `polytrim` -- trim leading coefficients from a polynomial.
-- `polyline` -- polynomial representing given straight line.
-
-Classes
--------
-- `Polynomial` -- polynomial class.
+.. autosummary::
+   :toctree: generated/
+
+   polyfromroots
+   polyroots
+   polyvalfromroots
+   polyvander
+   polyvander2d
+   polyvander3d
+   polycompanion
+   polyfit
+   polytrim
+   polyline
 
 See Also
 --------