Docs - Landing page (#145)

* Fix links in the docs prelude, add link to LAPACK project

* Refactor list of features to link at submodules instead of single traits

* Polishing

* Capitalize and characterize generator functions

* Restructure list and fix errors

* Add another decomposition

Author: LukeMathWalker

src/lib.rs

@@ -1,20 +1,39 @@
-//!  Linear algebra package for [rust-ndarray](https://github.com/bluss/rust-ndarray) using LAPACK via [stainless-steel/lapack](https://github.com/stainless-steel/lapack)
+//! The `ndarray-linalg` crate provides linear algebra functionalities for `ArrayBase`, the n-dimensional array data structure provided by [`ndarray`](https://github.com/rust-ndarray/ndarray).
 //!
-//!  Linear algebra methods
-//!  -----------------------
-//!  - [QR decomposition](qr/trait.QR.html)
-//!  - [singular value decomposition](svd/trait.SVD.html)
-//!  - [solve linear problem](solve/index.html)
-//!  - [solve linear problem for triangular matrix](triangular/trait.SolveTriangular.html)
-//!  - [inverse matrix](solve/trait.Inverse.html)
-//!  - [eigenvalue decomposition for Hermite matrix][eigh]
+//! `ndarray-linalg` leverages [LAPACK](http://www.netlib.org/lapack/)'s routines using the bindings provided by [blas-lapack-rs/lapack](https://github.com/blas-lapack-rs/lapack).
 //!
-//!  [eigh]:eigh/trait.Eigh.html
+//! Linear algebra methods
+//! -----------------------
+//! - Decomposition methods:
+//!     - [QR decomposition](qr/index.html)
+//!     - [Cholesky/LU decomposition](cholesky/index.html)
+//!     - [Eigenvalue decomposition for Hermite matrices](eigh/index.html)
+//!     - [**S**ingular **V**alue **D**ecomposition](svd/index.html)
+//! - Solution of linear systems:
+//!    - [General matrices](solve/index.html)
+//!    - [Triangular matrices](triangular/index.html)
+//!    - [Hermitian/real symmetric matrices](solveh/index.html)
+//! - [Inverse matrix computation](solve/trait.Inverse.html)
+//!
+//! Naming Convention
+//! -----------------------
+//! Each routine is usually exposed as a trait, implemented by the relevant types.
+//!
+//! For each routine there might be multiple "variants": different traits corresponding to the different ownership possibilities of the array you intend to work on.
+//!
+//! For example, if you are interested in the QR decomposition of a square matrix, you can use:
+//! - [QRSquare](qr/trait.QRSquare.html), if you hold an immutable reference (i.e. `&self`) to the matrix you want to decompose;
+//! - [QRSquareInplace](qr/trait.QRSquareInplace.html), if you hold a mutable reference (i.e. `&mut self`) to the matrix you want to decompose;
+//! - [QRSquareInto](qr/trait.QRSquareInto.html), if you can pass the matrix you want to decompose by value (e.g. `self`).
+//!
+//! Depending on the algorithm, each variant might require more or less copy operations of the underlying data.
+//!
+//! Details are provided in the description of each routine.
 //!
 //!  Utilities
 //!  -----------
-//!  - [assertions for array](index.html#macros)
-//!  - [generator functions](generate/index.html)
+//!  - [Assertions for array](index.html#macros)
+//!  - [Random matrix generators](generate/index.html)
 //!  - [Scalar trait](types/trait.Scalar.html)
 
 pub mod assert;