Documentation overhaul (#444)

Finalizing doc updates for tensor, sptensor, and ktensor. Closes #422

Author: dmdunla

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)
@@ -120,6 +120,14 @@ If you want to propose a change to Python Tensor Toolbox, follow these steps:
 1. **Update the Code**
     - Make the necessary updates in your local environment.
     - After making your changes, stage and commit them with an informative message.
+    - Make sure that the order of methods in classes is consistent with other code in the repository. Specifically, the order should be the following (with methods in each section sorted alphabetically):
+        1. `__slots__`
+        1. `__init__`
+        1. Property methods
+        1. classmethods (prefixed with `@classmethod`)
+        1. Public methods
+        1. Dunder methods (prefixed and suffixed with double underscores `__`)
+        1. Private methods (prefixed with an underscore `_`)
 
 1. **Push your Changes and Create a Pull Request**
     - Push your changes to the new branch in your fork of the repository.

docs/source/conf.py

@@ -50,6 +50,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx_toolbox.more_autodoc.overloads",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
@@ -72,6 +73,7 @@
 
 intersphinx_mapping = {
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "python": ("http://docs.python.org/3.10/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
 }
@@ -202,4 +204,4 @@
 # Autodoc settings
 autoclass_content = "class"
 autodoc_member_order = "bysource"
-autodoc_class_signature = "separated"
+autodoc_class_signature = "mixed"

docs/source/cpals.rst

@@ -1,8 +1,10 @@
-CP Alternating Least Squares (:obj:`cp_als`)
-============================================
-.. note::
-    
-     The ``cp_als`` function defined in ``cp_als.py`` has been promoted to the ``pyttb`` namespace.
+CP Alternating Least Squares (:obj:`pyttb.cp_als`)
+==================================================
+
+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,10 @@
-CP Alternating Poisson Regression (:obj:`cp_apr`)
-=================================================
-.. note::
-    
-     The ``cp_apr`` function defined in ``cp_apr.py`` has been promoted to the ``pyttb`` namespace.
+CP Alternating Poisson Regression (:obj:`pyttb.cp_apr`)
+=======================================================
+
+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/functionality.rst

@@ -1,8 +1,10 @@
 Generalized CP Optimization (:obj:`pyttb.gcp_opt`)
 ==================================================
-.. note::
-    
-     The ``gcp_opt`` function defined in ``gcp_opt.py`` has 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/gcpopt.rst

@@ -1,8 +1,9 @@
-Tucker Higher-Order SVD (:obj:`hosvd`)
-======================================
-.. note::
-    
-     The ``hosvd`` function defined in ``hosvd.py`` has been promoted to the ``pyttb`` namespace.
+Tucker Higher-Order SVD (:obj:`pyttb.hosvd`)
+============================================
 
+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/hosvd.rst

@@ -1,11 +1,12 @@
-Kruskal Tensor (:class:`ktensor`)
----------------------------------
-.. note::
-    
-     The ``ktensor`` class defined in ``ktensor.py`` has been promoted to the ``pyttb`` namespace.
+Kruskal Tensor (:class:`pyttb.ktensor`)
+=======================================
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.ktensor
     :members:
     :special-members:
-    :exclude-members: __dict__, __weakref__, __slots__
-    :show-inheritance:
+    :exclude-members: __init__, __dict__, __weakref__, __deepcopy__

docs/source/ktensor.rst

@@ -1,10 +1,15 @@
-Helper Functions (:mod:`pyttb_utils`, :mod:`khatrirao`)
---------------------------------------------------------
+Helper Functions (:mod:`pyttb.pyttb_utils`, :mod:`pyttb.khatrirao`)
+===================================================================
 
-.. autofunction:: pyttb.khatrirao.khatrirao
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. automodule:: pyttb.pyttb_utils
     :members:
     :special-members:
     :exclude-members: __dict__, __weakref__, __slots__
-    :show-inheritance:
+    :show-inheritance:
+
+.. autofunction:: pyttb.khatrirao.khatrirao

docs/source/pyttb_utils.rst

@@ -1,11 +1,13 @@
-Sparse Tensor as Matrix (:class:`sptenmat`)
--------------------------------------------
-.. note::
-    
-     The ``sptenmat`` class defined in ``sptenmat.py`` has been promoted to the ``pyttb`` namespace.
+Sparse Tensor as Matrix (:class:`pyttb.sptenmat`)
+=================================================
+
+For *all* examples in this document, the following module imports are assumed::
+
+    >>> import pyttb as ttb
+    >>> import numpy as np
 
 .. autoclass:: pyttb.sptenmat
     :members:
     :special-members:
-    :exclude-members: __dict__, __weakref__, __slots__
+    :exclude-members: __init__, __dict__, __weakref__, __deepcopy__
     :show-inheritance: