search

OttoStruve / muler

A Python package for working with pipeline-produced spectra from IGRINS, HPF, and Keck NIRSPEC
https://muler.readthedocs.io
MIT License
15 stars 9 forks source link

Tradeoffs in rendering tutorials on ReadTheDocs.org #100

Closed gully closed 2 years ago

gully commented 2 years ago

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.

Originally posted by @gully in https://github.com/OttoStruve/muler/issues/93#issuecomment-1110230316

gully commented 2 years ago

Another issue is that some tutorials rely on gollum, and gollum as currently implemented relies on local precomputed synthetic spectral models. So the muler tutorials that use gollum fail.

So we may want to return to auto rather than always option and re-upload some notebooks. Hmm... I wonder how other projects deal with these friction points.

gully commented 2 years ago

I've learned how to turn off rendering notebooks on an individual basis. So I am inclined to leave on the notebook rendering (or maybe turn it to auto). We have the issue that some of the notebooks I turned off have their output stripped with nbstripout, but that's solvable.

I'll change the title to reflect the new bottleneck.