Problems with Colab in Jupyter Notebooks

[DavidBAEpstein]

There are 12 jnbs in TIAToolbox. These each contain material about Colab. This material is almost identical in each jnb, but not 100% so. This causes maintenance problems, as was demonstrated recently when each jnb had to be altered in essentially identical ways. The right way to do this is to have just one copy of the material, with access from each notebook.

Unfortunately, it is not possible to include one jnb in another. So the best way to deal with the text cells is to move the material from the jnbs to a single rst file. This could be done by changing the name of the Algorithms directory to "Algorithms&Notes" (avoiding space characters in the directory name), and including the single rst file in this directory.

The apt-get code should be made into a python module, which the notebooks import.

Our group has somewhat self-contradictory philosophies. On the one hand it's important that "Run all" should work. On the other hand, use of an environmental variable, the obvious tool for making "Run All" work well, is said to be "mysterious and complicated" for naive users.

I am currently working on changing the raw source of our notebooks to as to make our two different methods (jnb and rtd) of rendering as consistent as possible.

1. Currently some of the text cells about Colab, and also the apt-get code cell, have metadata telling rtd to pay no attention to them. If a section heading is hidden from rtd, then rtd responds by regarding all the subsections as sections, with corresponding decisions by rtd about indexing and cross-references. (rtd and jnb have different ways of determining the level of a heading.)
2. Not all the Colab referencing text cells are hidden. When users try to find out about the use of Colab in our jnbs, they will be totally mystified by the resulting incoherence. If you fix your attention on a single Colab-referencing cell, then whether the cell is hidden or not could differ from one jnb to another, so that rtd is not only mysterious about Colab, but inconsistently mysterious from one notebook to another.