Documentation overhaul

CONTRIBUTING.md

@@ -76,7 +76,7 @@ current or filing a new [issue](https://github.com/sandialabs/pyttb/issues).
    ```
       1. For the CI version which is more strict
       ```commandline
-      sphinx-build ./docs/source ./docs/build -W -n --keep-going
+      sphinx-build ./docs/source ./docs/build -E -W --keep-going
       ```
       2. If not on Windows optionally add `-j auto` for parallelization
    2. Clear notebook outputs if run locally see `nbstripout` in our [pre-commit configuration](.pre-commit-config.yaml)

docs/source/cpals.rst

@@ -1,8 +1,13 @@
-CP Alternating Least Squares (:obj:`cp_als`)
-============================================
+CP Alternating Least Squares (:obj:`pyttb.cp_als`)
+==================================================
 .. note::
 
-     The ``cp_als`` function defined in ``cp_als.py`` has been promoted to the ``pyttb`` namespace.
+    Functions defined in ``cp_als.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autofunction:: pyttb.cp_als
 

docs/source/cpapr.rst

@@ -1,8 +1,13 @@
-CP Alternating Poisson Regression (:obj:`cp_apr`)
-=================================================
+CP Alternating Poisson Regression (:obj:`pyttb.cp_apr`)
+=======================================================
 .. note::
 
-     The ``cp_apr`` function defined in ``cp_apr.py`` has been promoted to the ``pyttb`` namespace.
+     Functions defined in ``cp_apr.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autofunction:: pyttb.cp_apr
 

docs/source/gcpopt.rst

@@ -2,7 +2,12 @@ Generalized CP Optimization (:obj:`pyttb.gcp_opt`)
 ==================================================
 .. note::
 
-     The ``gcp_opt`` function defined in ``gcp_opt.py`` has been promoted to the ``pyttb`` namespace.
+     Functions defined in ``gcp_optor.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autofunction:: pyttb.gcp_opt
 

docs/source/hosvd.rst

@@ -1,8 +1,12 @@
-Tucker Higher-Order SVD (:obj:`hosvd`)
-======================================
+Tucker Higher-Order SVD (:obj:`pyttb.hosvd`)
+============================================
 .. note::
 
-     The ``hosvd`` function defined in ``hosvd.py`` has been promoted to the ``pyttb`` namespace.
+    Functions defined in ``hosvd.py`` have been promoted to the ``pyttb`` namespace.
 
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autofunction:: pyttb.hosvd

docs/source/ktensor.rst

@@ -1,8 +1,13 @@
-Kruskal Tensor (:class:`ktensor`)
----------------------------------
+Kruskal Tensor (:class:`pyttb.ktensor`)
+=======================================
 .. note::
 
-     The ``ktensor`` class defined in ``ktensor.py`` has been promoted to the ``pyttb`` namespace.
+     Classes and functions defined in ``ktensor.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.ktensor
     :members:

docs/source/pyttb_utils.rst

@@ -1,10 +1,10 @@
-Helper Functions (:mod:`pyttb_utils`, :mod:`khatrirao`)
---------------------------------------------------------
-
-.. autofunction:: pyttb.khatrirao.khatrirao
+Helper Functions (:mod:`pyttb.pyttb_utils`, :mod:`pyttb.khatrirao`)
+===================================================================
 
 .. automodule:: pyttb.pyttb_utils
     :members:
     :special-members:
     :exclude-members: __dict__, __weakref__, __slots__
-    :show-inheritance:
+    :show-inheritance:
+
+.. autofunction:: pyttb.khatrirao.khatrirao

docs/source/sptenmat.rst

@@ -1,8 +1,13 @@
-Sparse Tensor as Matrix (:class:`sptenmat`)
--------------------------------------------
+Sparse Tensor as Matrix (:class:`pyttb.sptenmat`)
+=================================================
 .. note::
 
-     The ``sptenmat`` class defined in ``sptenmat.py`` has been promoted to the ``pyttb`` namespace.
+     Classes and functions defined in ``sptenmat.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.sptenmat
     :members:

docs/source/sptensor.rst

@@ -1,13 +1,18 @@
-Sparse Tensor (:class:`sptensor`)
----------------------------------
+Sparse Tensor (:class:`pyttb.sptensor`)
+=======================================
 .. note::
 
      Classes and functions defined in ``sptensor.py`` have been promoted to the ``pyttb`` namespace.
 
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
+
 .. autoclass:: pyttb.sptensor
     :members:
     :special-members:
-    :exclude-members: __dict__, __weakref__, __slots__
+    :exclude-members: __dict__, __weakref__, __slots__, __deepcopy__
     :show-inheritance:
 
 .. autofunction:: pyttb.sptenrand

docs/source/sumtensor.rst

@@ -1,9 +1,13 @@
-Sum Tensor (:class:`sumtensor`)
--------------------------------
+Sum Tensor (:class:`pyttb.sumtensor`)
+=====================================
 .. note::
 
-     The ``sumtensor`` class defined in ``sumtensor.py`` has been promoted to the ``pyttb`` namespace.
+     Classes and functions defined in ``sumtensor.py`` have been promoted to the ``pyttb`` namespace.
 
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.sumtensor
     :members:

docs/source/tenmat.rst

@@ -1,8 +1,13 @@
-Tensor as Matrix (:class:`tenmat`)
-----------------------------------
+Tensor as Matrix (:class:`pyttb.tenmat`)
+========================================
 .. note::
 
-     The ``tenmat`` class defined in ``tenmat.py`` has been promoted to the ``pyttb`` namespace.
+     Classes and functions defined in ``tenmat.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.tenmat
     :members:

docs/source/tensor.rst

@@ -1,5 +1,5 @@
 Dense Tensor (:class:`pyttb.tensor`)
-------------------------------------
+====================================
 .. note::
 
      Classes and functions defined in ``tensor.py`` have been promoted to the ``pyttb`` namespace.
@@ -9,10 +9,10 @@ For *all* examples in this document, the following module imports are assumed::
     >>> import pyttb as ttb
     >>> import numpy as np
 
-.. automodule:: pyttb.tensor
+.. autoclass:: pyttb.tensor
     :members:
     :special-members:
-    :exclude-members: __dict__, __weakref__, __slots__, __deepcopy__
+    :exclude-members: __init__, __dict__, __weakref__, __slots__, __deepcopy__
     :show-inheritance:
 
 .. autofunction:: pyttb.tenones

docs/source/ttensor.rst

@@ -2,7 +2,7 @@ Tucker tensor (:class:`pyttb.ttensor`)
 --------------------------------------
 .. note::
 
-     The ``ttensor`` class defined in ``ttensor.py`` has been promoted to the ``pyttb`` namespace.
+     Classes and functions defined in ``sptensor.py`` have been promoted to the ``pyttb`` namespace.
 
 .. autoclass:: pyttb.ttensor
     :members:

docs/source/tuckerals.rst

@@ -2,6 +2,11 @@ Tucker Alternating Least Squares (:obj:`pyttb.tucker_als`)
 ==========================================================
 .. note::
 
-     The ``tucker_als`` function defined in ``tucker_als.py`` has been promoted to the ``pyttb`` namespace.
+     Functions defined in ``tucker_als.py`` have been promoted to the ``pyttb`` namespace.
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autofunction:: pyttb.tucker_als

pyttb/tensor.py

@@ -49,15 +49,75 @@
 class tensor:  # noqa: PLW1641
     """Class for dense tensors.
 
-    Attributes
+    Parameters
     ----------
-        data : numpy.ndarray
-            Data of the tensor
-        shape : Tuple[int]
-            Size of the tensor
+    data : optional
+        Source data as :class:`numpy.ndarray`
+    shape : optional
+        Shape of the tensor as a :class:`tuple` or any iterable array of integers.
+        A single integer means that the tensor should be a 1D array.
+        If no shape is given, defaults to :attr:`numpy.ndarray.shape` of ``data``.
+        Otherwise, the data is reshaped to the specified shape.
+    copy : optional
+        Whether to deep copy (versus reference) the data.
+        By default, the data is deep copied.
+
+    **Attributes**
+
+    - **data** (:class:`numpy.ndarray`) : Data of the tensor
+    - **shape** (:class:`tuple`) : Size of the tensor
 
-    Instances of :class:`pyttb.tensor` can be created using
-    :meth:`pyttb.tensor.tensor.__init__` or the following methods:
+    Examples
+    --------
+    Create a :class:`pyttb.tensor` from a three-way :class:`numpy.ndarray`::
+
+        >>> data = np.array([[[1,13],[5,17],[9,21]],
+        ... [[2,14],[6,18],[10,22]],
+        ... [[3,15],[7,19],[11,23]],
+        ...  [[4,16],[8,20],[12,24]]])
+        >>> T = ttb.tensor(data)
+        >>> print(T)
+        tensor of shape (4, 3, 2) with order F
+        data[:, :, 0] =
+        [[ 1  5  9]
+         [ 2  6 10]
+         [ 3  7 11]
+         [ 4  8 12]]
+        data[:, :, 1] =
+        [[13 17 21]
+         [14 18 22]
+         [15 19 23]
+         [16 20 24]]
+
+    Create a :class:`pyttb.tensor` from a :class:`numpy.ndarray` vector and
+    reshape it::
+
+        >>> data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+        ... 17, 18, 19, 20, 21, 22, 23, 24])
+        >>> T = ttb.tensor(data, shape=(4, 3, 2))
+        >>> print(T)
+        tensor of shape (4, 3, 2) with order F
+        data[:, :, 0] =
+        [[ 1  5  9]
+         [ 2  6 10]
+         [ 3  7 11]
+         [ 4  8 12]]
+        data[:, :, 1] =
+        [[13 17 21]
+         [14 18 22]
+         [15 19 23]
+         [16 20 24]]
+
+    Create an empty :class:`pyttb.tensor`::
+
+        >>> T = ttb.tensor()
+        >>> print(T)
+        empty tensor of shape ()
+        data = []
+
+    Notes
+    -----
+    Instances of :class:`pyttb.tensor` can also be created using the following methods:
 
         * :meth:`from_function` - Create a tensor from a function
         * :meth:`copy` - Make a deep copy of a tensor
@@ -82,71 +142,6 @@ def __init__(
         shape: Shape | None = None,
         copy: bool = True,
     ):
-        """
-        Create a :class:`pyttb.tensor`.
-
-        Parameters
-        ----------
-        data : optional
-            Source data as :class:`numpy.ndarray`
-        shape : optional
-           Shape of the tensor as a :class:`tuple` or any iterable array of integers.
-           A single integer means that the tensor should be a 1D array.
-           If no shape is given, defaults to :attr:`numpy.ndarray.shape` of ``data``.
-           Otherwise, the data is reshaped to the specified shape.
-        copy : optional
-            Whether to deep copy (versus reference) the data.
-            By default, the data is deep copied.
-
-        Examples
-        --------
-        Create a :class:`pyttb.tensor` from a three-way :class:`numpy.ndarray`::
-
-            >>> data = np.array([[[1,13],[5,17],[9,21]],
-            ... [[2,14],[6,18],[10,22]],
-            ... [[3,15],[7,19],[11,23]],
-            ...  [[4,16],[8,20],[12,24]]])
-            >>> T = ttb.tensor(data)
-            >>> print(T)
-            tensor of shape (4, 3, 2) with order F
-            data[:, :, 0] =
-            [[ 1  5  9]
-             [ 2  6 10]
-             [ 3  7 11]
-             [ 4  8 12]]
-            data[:, :, 1] =
-            [[13 17 21]
-             [14 18 22]
-             [15 19 23]
-             [16 20 24]]
-
-        Create a :class:`pyttb.tensor` from a :class:`numpy.ndarray` vector and
-        reshape it::
-
-            >>> data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
-            ... 17, 18, 19, 20, 21, 22, 23, 24])
-            >>> T = ttb.tensor(data, shape=(4, 3, 2))
-            >>> print(T)
-            tensor of shape (4, 3, 2) with order F
-            data[:, :, 0] =
-            [[ 1  5  9]
-             [ 2  6 10]
-             [ 3  7 11]
-             [ 4  8 12]]
-            data[:, :, 1] =
-            [[13 17 21]
-             [14 18 22]
-             [15 19 23]
-             [16 20 24]]
-
-        Create an empty :class:`pyttb.tensor`::
-
-            >>> T = ttb.tensor()
-            >>> print(T)
-            empty tensor of shape ()
-            data = []
-
-        """
         if data is None:
             # EMPTY / DEFAULT CONSTRUCTOR
             self.data: np.ndarray = np.array([], order=self.order)