TL;DR

[hugobuddel]

Some usability issues that we identified today:

• We shouldn't use the term TL;DR, and instead explain what we mean. Especially in the notebooks and in the names of the notebooks.
• The TL;DR at the end of https://github.com/AstarVienna/ScopeSim/blob/dev_master/docs/source/examples/1_scopesim_intro.ipynb should not be a markdown cell but a regular cell so it will be ran in the CI and we get notified if it breaks. This might also apply to other cells.
• The code in markdown cells should be runnable by copy pasting it in a normal cell. E.g. cell that ends with a line with a colon like class MyClass: should be followed by a line with ellipsis, ....
• The notebooks contain some code to set the local_package_path for the benefit of Readthedocs. This is confusing and should be rephrased to be useful for the user.

About the last point, the top cell of each notebook currently contains something like

# [Required for Readthedocs] Comment out this line if running locally
tmpdir = TemporaryDirectory()
sim.rc.__config__["!SIM.file.local_packages_path"] = tmpdir.name

Instead it could contain something like

# The code in the next cell will download instrument package from the IRDB.
# If you have already downloaded them before, you can specify the directory
# by setting sim.rc.__config__["!SIM.file.local_packages_path"]
# Here we create a temporary directory and use that, which is useful when
# generating the documentation on readthedocs. 
# The local directory will be used if you don't specify any directory, e.g. by commenting out the next two lines.
tmpdir = TemporaryDirectory()
sim.rc.__config__["!SIM.file.local_packages_path"] = tmpdir.name

Or something similar

[teutoburg]

I think I got all cases of this in the ScopeSim repo. There are however more hidden in some instrument packages in the IRDB repo. I'll transfer the issue and solve the cases there separately...

[teutoburg]

There are several notebooks also in this repo where this issue exists. Reopening it here to deal with that...

[oczoske]

I can take care of the local_package_path issue in the METIS notebooks.

A general remark: jupyter notebooks should be saved empty, without the code output (Kernel -> Restart & Clear Output). The resulting file size is smaller and diffs between versions are much more manageable that way, in particular when the output contains plots and images.

[hugobuddel]

For MICADO I 'solved' the local_package_path simply by adding a symlink called inst_pkgs that points to the root of the repository, and subsequently commented out all the 'download this package' line.

[hugobuddel]

About the figures, it is good to be able to see the figures. That way people know at least what to expect before they run them.

Perhaps we can ensure that the figures are included on read the docs, then people can use that as a reference. But currently the read the docs does not have figures, at least not for these notebooks: https://irdb.readthedocs.io/en/latest/MICADO/docs/example_notebooks/1_scopesim_MCAO_4mas_galaxy.html#

I prefer to keep the figures in the repository as long as they are unavailable on read the docs.

We could also make the notebooks fully reproducible, e.g. by setting the random seeds. Then the figures shouldn't change that often, and then I'd be fine with storing them.

[hugobuddel]

For MICADO I 'solved' the local_package_path simply by adding a symlink called inst_pkgs that points to the root of the repository, and subsequently commented out all the 'download this package' line.

Note that a benefit of the symlink is that running the notebooks will actually use the IRDB from this repository and thus the same version as the notebooks themselves. Otherwise the notebooks will download a package that might, or might not, correspond to the specific commit that the notebooks are from.