update docs

- add "internals" section
- add a slight clarification to manual

docs/index.rst

@@ -51,6 +51,7 @@ Content
 
     formulation
     manual
+    internals
     benchmarks
     api
     changelog

docs/internals.rst

@@ -0,0 +1,57 @@
+.. _internals:
+
+.. currentmodule:: csaps
+
+Internals
+=========
+
+Spline Representation
+---------------------
+
+The computed splines are represented by classes :class:`SplinePPForm` for univariate/multivariate
+and :class:`NdGridSplinePPForm` for nd-gridded data.
+
+The spline coefficients are stored in the numpy array. It is 2D 1xM array for univariate data,
+2D NxM array for multivariate data and 2D/ND array (tensor-product of univariate spline coefficients)
+for nd-gridded data.
+
+Let's look at a simple example.
+
+The multivariate data::
+
+    x = [1, 2, 3, 4]
+    y = [(1, 2, 3, 4), (5, 6, 7, 8)]
+
+Compute the spline:
+
+.. code-block:: python
+
+    >>> s = csaps(x, y).spline
+
+And print the spline info and coefficients array:
+
+.. code-block:: python
+
+    >>> print(s)
+
+    SplinePPForm
+      breaks: [1. 2. 3. 4.]
+      coeffs: shape (2, 12)
+      pieces: 3
+      order: 4
+      ndim: 2
+
+    >>> print(s.coeffs)
+
+    [[0. 0. 0. 0. 0. 0. 1. 1. 1. 1. 2. 3.]
+     [0. 0. 0. 0. 0. 0. 1. 1. 1. 5. 6. 7.]]
+
+Each row in the array contain coefficients for all spline pieces for corresponding data.
+In our case we have 2D Y-data with shape (2, 4) and have the coefficients array with shape (2, 12)
+
+    - 2 rows: 2 dimensions in the data
+    - 12 columns: 3 pieces of the cubic spline (4-order)
+
+The spline pieces for each dimension are composed sequentially in the one row.
+Such representation allows us to compute tensor-product for nd-grid data and evaluate splines
+without superfluous manipulations and reshapes of the coefficients array.

docs/manual.rst

@@ -197,8 +197,8 @@ where
     - ``y`` -- the data values. For univariate case it is vector with the same size as ``x``,
       for multivariate case it is a sequence of vectors or nd-array, and for nd-gridded data
       it is nd-array
-    - ``xi`` -- the data sites for smoothed data. It is shape-like ``x`` data and in the same
-      range as ``x``, but usually has more interpolated points
+    - ``xi`` -- the data sites for smoothed data (output mesh). It is shape-like ``x`` and in the same
+      range as ``x``, but usually it has more interpolated points
     - ``smooth`` -- the smoothing parameter in the range ``[0, 1]``
 
 
@@ -384,7 +384,7 @@ The example for univariate data:
     Spline smoothing parameter: 0.8999999999999999
     Spline description: SplinePPForm
       breaks: [-5. -4. -3. -2. -1.  0.  1.  2.  3.  4.  5.]
-      coeffs: (10, 4) shape
+      coeffs: shape (1, 40)
       pieces: 10
       order: 4
       ndim: 1