Should the notebooks use mocks?

[teutoburg]

The issue

Some of the documentation notebooks (getting_started.ipynb, bang_strings.ipynb and effects_include.ipynb) use load_example_optical_train(), which is actually a (sort of) mock construct we use for testing. While I understand the benefits of using something like basic_instrument for the notebooks to keep it simple, I'm not sure it's a good idea to mix tests and docs in that way, especially given that the tests are not always included in a release (e.g. 0.7.0), so users might have issues running the notebook with such a release.

Possible solutions

Via IRDB

Make basic_instrument an IRDB package so it can be used outside the test suite. The load_example_optical_train() function does little more than create the UserCommands and OpticalTrain instances, so doing that in the notebook doesn't add a lot there.

Advantages

• basic_instrument could be used anywhere just like a normal package.
• If we use it in an instructional way, it might be better to use it in the same way as any other package, so new users don't get confused.

Disadvantages

• Yet another IRDB package 😐
• Should avoid the need to download something just to run the tests...

Move it somewhere else

We could just move the whole thing outside the tests directory, and maybe retain a mock function calling it from somewhere else.

Advantages

• Still local-only, no download required.
• Doesn't matter if tests are included in release or not.

Disadvantages

• More data files in the package

Conclusion

So anyway, thoughts? @hugobuddel @astronomyk

Not urgent et al., just something I ran into while working on #285

[hugobuddel]

My thoughts:

• The basic_instrument should be part of the ScopeSim repository, because that makes the project self-contained. The IRDB should be 'extra' and not required to run the tests / examples. (Unless the example is specifically about the IRDB.)
• The tests should be included with the package, because this gives end-users an easy way to check whether their installation is working properly. Having the tests in the package also helps repackaging systems like conda/nix/guix.
• It would perhaps be better to have the basic_instrument elsewhere in the repository, but I don't think that is important enough to deal with now.

So my suggested course of action is:

• Soon: ensure the tests (and the mock data) are part of the PyPI package. Should be easy, perhaps just put them in the MANIFEST?
• Later, perhaps: move the basic_instrument to another location in the repository.