Issues with lifting of classes and functions into pyttb namespace, documentation, etc.

[tgkolda]

I have been very confused about the qualification of names of classes and functions within PyTTB until I found these (sneaky) lines of code in the init file:

pyttb/pyttb/__init__.py

Lines 14 to 32 in 6279f88

	from pyttb.cp_als import cp_als
	from pyttb.cp_apr import cp_apr
	from pyttb.export_data import export_data
	from pyttb.gcp_opt import gcp_opt
	from pyttb.hosvd import hosvd
	from pyttb.import_data import import_data
	from pyttb.khatrirao import khatrirao
	from pyttb.ktensor import ktensor
	from pyttb.matlab import matlab_support
	from pyttb.sptenmat import sptenmat
	from pyttb.sptensor import sptendiag, sptenrand, sptensor
	from pyttb.sptensor3 import sptensor3
	from pyttb.sumtensor import sumtensor
	from pyttb.symktensor import symktensor
	from pyttb.symtensor import symtensor
	from pyttb.tenmat import tenmat
	from pyttb.tensor import tendiag, teneye, tenones, tenrand, tensor, tenzeros
	from pyttb.ttensor import ttensor
	from pyttb.tucker_als import tucker_als

The reason I was confused is that the sphinx documentation wants to include the module names in the documentation. However, using the module names will cause PyTTB to break. Observe:

This is really confusing!!

I could envision a few possible fixes. I'm guessing the error that I'm having is that by importing tensor directly as a class it no longer makes sense to reference it as a module, so one recommendation is that the modules be named differently than the classes. If they are to be hidden, then maybe an underscore or something.

Then, in the documentation, we need to be ultra careful about the way that the methods are documented. Calling automodule automatically inserts the module name. So, we need to instead use autoclass and autofunction directly.

[tgkolda]

As another example, it seems that the function ttb.cp_apr.vectorize_for_mu is not accessible because cp_apr has been lifted.

[tgkolda]

One proposal to consider is naming "hidden modules" as followed by _hm or something. For example, tensor.py would become tensor_hm.py.

[ntjohnson1]

One thing I'm partial to is to potentially introduce more nesting. I think we originally flattened things to better match MATLAB.

When I started to play with rust I had the layout look like

/ttb
   /tensors
      dense
      sparse
      kruskal
  /cp
     als

We can keep the names as is but a different logical grouping would potentially remove some of the confusion about the import paths vs the code paths. Also importing everything in the flat layout has made a few things minorly inconvenient because we had to be more careful about import ordering.

[tgkolda]

I think the main caution at this stage is to be ultra careful about the way that the methods are documented. Calling automodule automatically inserts the module name. So, we need to instead use autoclass and autofunction directly.

[dmdunla]

Closing, as this is superceded by Issue #422 / PR #444