Where is tenones in the readthedocs?

[tgkolda]

I can't find tenones in the readthedocs documentation. (It's also a bit confusing to me that it's inside the tensor class file rather than in the utils one.) Relatedly, where are the utils documented?

[tgkolda]

Relatedly, I can see that there is an rst file for pyttb_utils and that it's included in the tensor_classes.rst, but I cannot see any of the functions documented anywhere.

Any ideas how to fix this? I'm not super familiar with this documentation generator.

[ntjohnson1]

cp_apr is also a collection of functions and not a class. It looks like adding the magic term that is in cp_apr.rst but not pyttb_utils.rst generates the function docs for me. I assume adding that same term to tensor will make tenones pop up as well. I don't have a source for this (a quick google didn't turn up an answer immediately)

 git diff .\docs\
diff --git a/docs/source/pyttb_utils.rst b/docs/source/pyttb_utils.rst
index cf10664..884e68f 100644
--- a/docs/source/pyttb_utils.rst
+++ b/docs/source/pyttb_utils.rst
@@ -3,6 +3,7 @@ pyttb.pyttb_utils

 .. automodule:: pyttb.pyttb_utils
     :members:
+    :undoc-members:
     :special-members:
     :exclude-members: __dict__, __weakref__, __slots__, __init__
     :show-inheritance:

[ntjohnson1]

The index doesn't show tenones so it looks like we just generated the tensor class but not the supporting functions. https://pyttb.readthedocs.io/en/stable/genindex.html

Right now our namespace hierarchy is very flat to try to mirror MATLAB but it makes the code layout more challenging. There are circular dependency issues with putting everything in the utils file (the tensors depend on the utils but tenones returns a tensor). Also right now most of the utils are more developer focused than user focused.

[tgkolda]

That helps to understand the choices.

It sounds like it might be worth considering splitting the utilities into 2-3 parts.

1. User-facing utilities that assume the existence of all the tensor classes. Functions like tenones would go here.

2. User-facing utilities that do not assume the existence of any tensor class, like tuple-linear index conversion routines. Well-documented.

3. Developer utilities that do not reference the tensor classes. These would still be documented, but with the caveat of being developer utilities and not meant for general usage.

[ntjohnson1]

Yes, I think that makes sense. Just haven't had bandwidth to explore it. (It's also will probably be a breaking change so need to figure out semver release strategy)

[tgkolda]

Yes, here is how I think tensor.rst should be changed:

pyttb.tensor
--------------------

.. automodule:: pyttb.tensor
    :members:
    :special-members:
    :exclude-members: __dict__, __weakref__, __slots__, __init__, mttv_left, mttv_mid, mttv_right, min_split
    :show-inheritance:

Note that I've hidden some of the functions that are presumbly for developers only. I might suggest to prepend them with tt_. That's usually how we differentiated developer functions with tensor toolbox for MATLAB.

[ntjohnson1]

For python the underscore prefix is how private methods are denoted and I think those are skipped for the auto doc (it would be a more standard/automatic way to manage it without needing to touch the rest).

Speaking of cleanup I think we should strip all tt_ prefixes in the python code base because the import mechanism makes it explicit which package the functions come from (where it's needed in Matlab since everything gets imported into a global namespace)

[tgkolda]

This was reported in #399