JOSS Review - Example usage and notebooks have path inconsistencies

[wtgee]

If I follow the instructions for Running the tests it has me put the example data (I used a symlink) in tests/data/muler_example_data, which works fine, with all tests passing when I run py.test -vs.

However, if I go to the next page in the documentation, the Quickstart, and run the corresponding https://github.com/OttoStruve/muler/blob/main/docs/quickstart.ipynb file, I get a FileNotFoundError because it assumes a slightly different path. In fact this first example should point to ../tests/data/muler_example_data/IGRINS/01_IGRINS_test_data/ as the base path.

---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Input In [2], in <cell line: 1>()
----> 1 spec = IGRINSSpectrum(file='../tests/data/SDCH_20201202_0059.spec_a0v.fits')

Some of the notebooks seem to work with default setup and some don't so I would recommend a quick double-check of them all or a change of the py.test path for the example data.

[gully]

Thank you 🙏 !

Note to self: this friction point may suggest that we build the notebooks programmatically with each commit, as is possible and common practice with various Sphinx extensions (I think lightkurve does that, for example). It adds some computation overhead to the continuous integration, so not necessarily free.

But in the short term, a quick fix of getting the parths consistent will do the job. Thank you again! 😃

[gully]

Ok, after lots of back-and-forths, I got readthedocs (RTD) to render the tutorials! Yay! 🥳

The one hiccup is that RTD does not play nicely with importlib_resources, I think it has something to do with how RTD makes paths to the source code it installs, relative vs. absolute paths, and other finicky things.

My workaround is to simply (and heretically) pip install muler to render the documentation. That's heretical because it means any code change will not get instantaneously reflected into the live documentation, which is a big loss. Big enough that we may want to reconsider this choice. Feedback is welcomed.

On the other hand it means that we have a renewed incentive to make regular pip releases in order to keep the docs up-to-date, which will make pip a more up-to-date option for those who don't want to do the full developer version.