diff --git a/docs/source/_templates/autosummary/base.rst b/docs/source/_templates/autosummary/base.rst new file mode 100644 index 00000000..e4862661 --- /dev/null +++ b/docs/source/_templates/autosummary/base.rst @@ -0,0 +1,5 @@ +{{ objname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} \ No newline at end of file diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 00000000..0bae7ba5 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,30 @@ +{{ objname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :special-members: + :exclude-members: __dict__, __weakref__, __slots__, __init__, __deepcopy__, __hash__ + + {% block attributes %} + {% if attributes %} + .. rubric:: Attributes + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ name }}.{{ item }} + {% endfor %} + {% endif %} + {% endblock %} + + {% block methods %} + {% if methods %} + .. rubric:: Methods + .. autosummary:: + :toctree: + {% for item in methods %} + {{ name }}.{{ item }} + {% endfor %} + {% endif %} + {% endblock %} \ No newline at end of file diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 00000000..a00d76e8 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,23 @@ +{{ fullname | escape | underline }} + +.. rubric:: Description +.. automodule:: {{ fullname }} +.. currentmodule:: {{ fullname }} + +{% if classes %} +.. rubric:: Classes +.. autosummary:: + :toctree: + {% for class in classes %} + {{ class }} + {% endfor %} +{% endif %} + +{% if functions %} +.. rubric:: Functions +.. autosummary:: + :toctree: + {% for function in functions %} + {{ function }} + {% endfor %} +{% endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py index dee16974..ee05732f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,10 +52,11 @@ "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.napoleon", + "sphinx.ext.autosummary", "myst_nb", ] -autodoc_preserve_defaults = True +# autodoc_preserve_defaults = True myst_enable_extensions = [ "amsmath", @@ -197,6 +198,9 @@ # -- Extension configuration ------------------------------------------------- # Autodoc settings -autoclass_content = "class" +# autoclass_content = "both" autodoc_member_order = "bysource" -autodoc_class_signature = "separated" +autosummary_generate = True +autosummary_generate_overwrite = False +autosummary_ignore_module_all = False +autosummary_imported_members = True diff --git a/docs/source/functionality.rst b/docs/source/functionality.rst deleted file mode 100644 index a8e30003..00000000 --- a/docs/source/functionality.rst +++ /dev/null @@ -1,6 +0,0 @@ -:orphan: - -Functionality -************* - -In construction \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 930010c1..850c7cf5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -71,11 +71,11 @@ This is relevant for indexing. In the future we hope to extend support for both. getting_started.rst -Python API +Python Reference ================ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 reference.rst diff --git a/docs/source/ktensor.rst b/docs/source/ktensor.rst deleted file mode 100644 index 66e23b5c..00000000 --- a/docs/source/ktensor.rst +++ /dev/null @@ -1,11 +0,0 @@ -Kruskal Tensor (:class:`ktensor`) ---------------------------------- -.. note:: - - The ``ktensor`` class defined in ``ktensor.py`` has been promoted to the ``pyttb`` namespace. - -.. autoclass:: pyttb.ktensor - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: \ No newline at end of file diff --git a/docs/source/pyttb_utils.rst b/docs/source/pyttb_utils.rst deleted file mode 100644 index 7cc02f4c..00000000 --- a/docs/source/pyttb_utils.rst +++ /dev/null @@ -1,8 +0,0 @@ -Helper Functions (:mod:`pyttb_utils`) -------------------------------------- - -.. automodule:: pyttb.pyttb_utils - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: \ No newline at end of file diff --git a/docs/source/reference.rst b/docs/source/reference.rst index 46cab023..f634a618 100644 --- a/docs/source/reference.rst +++ b/docs/source/reference.rst @@ -1,8 +1,20 @@ -Reference (:mod:`pyttb`) -======================== +Reference (:class:`pyttb`) +========================== -.. toctree:: - :maxdepth: 2 +.. rubric:: Description +.. automodule:: pyttb +.. currentmodule:: pyttb - tensor_classes.rst - algorithms.rst + +.. rubric:: Classes +.. autosummary:: + :toctree: generated + + pyttb.tensor + pyttb.sptensor + pyttb.ktensor + pyttb.ttensor + pyttb.sumtensor + pyttb.tenmat + pyttb.sptenmat + pyttb.pyttb_utils diff --git a/docs/source/sptenmat.rst b/docs/source/sptenmat.rst deleted file mode 100644 index b9554a53..00000000 --- a/docs/source/sptenmat.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sparse Tensor as Matrix (:class:`sptenmat`) -------------------------------------------- -.. note:: - - The ``sptenmat`` class defined in ``sptenmat.py`` has been promoted to the ``pyttb`` namespace. - -.. autoclass:: pyttb.sptenmat - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: \ No newline at end of file diff --git a/docs/source/sptensor.rst b/docs/source/sptensor.rst deleted file mode 100644 index 638eb8c9..00000000 --- a/docs/source/sptensor.rst +++ /dev/null @@ -1,14 +0,0 @@ -Sparse Tensor (:class:`sptensor`) ---------------------------------- -.. note:: - - Classes and functions defined in ``sptensor.py`` have been promoted to the ``pyttb`` namespace. - -.. autoclass:: pyttb.sptensor - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: - -.. autofunction:: pyttb.sptenrand -.. autofunction:: pyttb.sptendiag \ No newline at end of file diff --git a/docs/source/sumtensor.rst b/docs/source/sumtensor.rst deleted file mode 100644 index d9f793e5..00000000 --- a/docs/source/sumtensor.rst +++ /dev/null @@ -1,12 +0,0 @@ -Sum Tensor (:class:`sumtensor`) -------------------------------- -.. note:: - - The ``sumtensor`` class defined in ``sumtensor.py`` has been promoted to the ``pyttb`` namespace. - - -.. autoclass:: pyttb.sumtensor - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: \ No newline at end of file diff --git a/docs/source/tenmat.rst b/docs/source/tenmat.rst deleted file mode 100644 index b4ea5044..00000000 --- a/docs/source/tenmat.rst +++ /dev/null @@ -1,11 +0,0 @@ -Tensor as Matrix (:class:`tenmat`) ----------------------------------- -.. note:: - - The ``tenmat`` class defined in ``tenmat.py`` has been promoted to the ``pyttb`` namespace. - -.. autoclass:: pyttb.tenmat - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: \ No newline at end of file diff --git a/docs/source/tensor.rst b/docs/source/tensor.rst deleted file mode 100644 index f27fe87e..00000000 --- a/docs/source/tensor.rst +++ /dev/null @@ -1,22 +0,0 @@ -Dense Tensor (:class:`tensor`) ------------------------------- -.. note:: - - Classes and functions defined in ``tensor.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 - -.. automodule:: pyttb.tensor - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: - -.. autofunction:: pyttb.tenones -.. autofunction:: pyttb.tenzeros -.. autofunction:: pyttb.tenrand -.. autofunction:: pyttb.tendiag -.. autofunction:: pyttb.teneye diff --git a/docs/source/tensor_classes.rst b/docs/source/tensor_classes.rst deleted file mode 100644 index 56fb9f21..00000000 --- a/docs/source/tensor_classes.rst +++ /dev/null @@ -1,15 +0,0 @@ -Tensor Classes -============== - -.. toctree:: - :maxdepth: 1 - - tensor.rst - sptensor.rst - ktensor.rst - ttensor.rst - sumtensor.rst - tenmat.rst - sptenmat.rst - pyttb_utils.rst - diff --git a/docs/source/ttensor.rst b/docs/source/ttensor.rst deleted file mode 100644 index b803d318..00000000 --- a/docs/source/ttensor.rst +++ /dev/null @@ -1,11 +0,0 @@ -Tucker tensor (:class:`ttensor`) --------------------------------- -.. note:: - - The ``ttensor`` class defined in ``ttensor.py`` has been promoted to the ``pyttb`` namespace. - -.. autoclass:: pyttb.ttensor - :members: - :special-members: - :exclude-members: __dict__, __weakref__, __slots__ - :show-inheritance: diff --git a/pyttb/tensor.py b/pyttb/tensor.py index 1fe81dd3..b6b7e9a8 100644 --- a/pyttb/tensor.py +++ b/pyttb/tensor.py @@ -54,15 +54,70 @@ class tensor: """Class for dense tensors. - Attributes + Parameters ---------- - data : numpy.ndarray - Data of the tensor - shape : tuple of integers - 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. - Instances of :class:`pyttb.tensor` can be created using :meth:`__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 @@ -87,71 +142,6 @@ def __init__( shape: Optional[Shape] = 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)