Various documentation updates, on top of Nick's Fortran fixes.

.gitignore

@@ -6,6 +6,7 @@ dist/
 tests/__pycache__
 pyttb/__pycache__
 build/
+_build/
 .coverage
 .ipynb_checkpoints
 htmlcov

docs/source/index.rst

@@ -4,16 +4,25 @@ pyttb: Python Tensor Toolbox
 ****************************
 Tensors (also known as multidimensional arrays or N-way arrays) are used
 in a variety of applications ranging from chemometrics to network
-analysis.
+analysis. This Python package is an adaptation of the 
+`Tensor Toolbox for MATLAB <https://www.tensortoolbox.org>`_.
 
--  Install the latest release from pypi (``pip install pyttb``).
 -  This is open source software. Please see `LICENSE`_ for the
    terms of the license (2-clause BSD).
 -  For more information or for feedback on this project, please `contact us`_.
 
 .. _`LICENSE`: ../../../LICENSE
 .. _contact us: #contact
 
+Installing
+==========
+
+* Via pypi
+   -  Install the latest release from pypi (``pip install pyttb``).
+* From source
+   -  Clone the repository from `github <https://github.com/sandialabs/pyttb>`_.
+   -  Install the package with ``pip install .`` from the pyttb root directory.
+
 Functionality
 ==============
 pyttb provides the following classes and functions

pyttb/tensor.py

@@ -50,25 +50,15 @@
 
 
 class tensor:
-    """
-    TENSOR Class for dense tensors.
-
-    Contains the following data members:
+    """Class for dense tensors. 
+    
+    **Members**
 
-    ``data``: :class:`numpy.ndarray` dense array containing the data elements
-    of the tensor.
+    * ``data``: :class:`numpy.ndarray` containing the data elements of the tensor stored, by default, in Fortran order.
 
-    Instances of :class:`pyttb.tensor` can be created using `__init__()` or
-    the following method:
+    * ``shape``: :class:`tuple` of integers containing the size of each mode of the tensor. *Technically, this is redudant since the shape can be inferred from the data. This is an artifact of the transfer from the MATLAB Tensor Toolbox because MATLAB does not propertly store the size of a 1D tensor.*
 
-      * :meth:`from_function`
-
-    Examples
-    --------
-    For all examples listed below, the following module imports are assumed:
-
-    >>> import pyttb as ttb
-    >>> import numpy as np
+    
     """
 
     __slots__ = ("data", "shape")
@@ -79,11 +69,9 @@ def __init__(
         shape: Optional[Shape] = None,
         copy: bool = True,
     ):
-        """Create a :class:`pyttb.tensor` from a :class:`numpy.ndarray`.
-
-        Note that 1D tensors (i.e., when len(shape)==1) contains a data
-        array that follow the Numpy convention of being a row vector.
-
+        """
+        **Constructor**
+        
         Parameters
         ----------
         data:
@@ -95,6 +83,12 @@ def __init__(
 
         Examples
         --------
+
+        For *all* examples in this document, the following module imports are assumed:
+
+        >>> import pyttb as ttb
+        >>> import numpy as np
+
         Create an empty :class:`pyttb.tensor`:
 
         >>> T = ttb.tensor()
@@ -110,6 +104,10 @@ def __init__(
         data[:, :] =
         [[1 2]
          [3 4]]
+
+         See Also
+         --------
+            :meth:`from_function`
         """
         if data is None:
             # EMPTY / DEFAULT CONSTRUCTOR
@@ -1099,6 +1097,7 @@ def nvecs(self, n: int, r: int, flipsign: bool = True) -> np.ndarray:
         Xn = self.to_tenmat(rdims=np.array([n])).double()
         y = Xn @ Xn.T
 
+        # TODO (TK) We shouldn't use sparse library functions. RandSVD would probably be better.
         if r < y.shape[0] - 1:
             w, v = scipy.sparse.linalg.eigsh(y, r)
             v = v[:, (-np.abs(w)).argsort()]