After having struggled with updating TuringTutorials months ago, I have been long on the lookout for a good system to automatically build notebooks to a pretty website to show the code and outputs. Thanks to many different comments on different PRs, I learned that the requirements were to:
- Evaluate notebooks independently in CI.
- Allow people to easily update notebooks.
- Have independent manifests for each notebook (otherwise, updating one tutorial may be nearly impossible because dependencies have to be the same everywhere).
- Have a cache, that is, avoid re-running unchanged notebooks
- Very importantly: reliably fail on error. This is a must-have at all times when a public website is generated.
- Print package versions at the bottom of the page.
- Make it easy for people to run the code themselves.
At TuringTutorials, we’ve implemented large parts of this logic manually. This is all very tricky, you’ll run into things like:
and a ton of caching problems. All not impossible problems to overcome, but annoying nevertheless; especially if some tutorials take >20 minutes to run and note that this is on top of maintaining the tutorials in the first place.
However, that package is quite bare-bones and generating a pretty website with it wasn’t that easy. So, I would like to annouce that there is now a template repository including caching, parallel building, GitHub Pages setup, fancy CSS styled appearance, good appearance on phone, a nice favicon, Highlight.js and, of course, JuliaMono
See the Julia Tutorials Template website.
I hope that this can make writing tutorials easier for more people. I’m looking forward to seeing more pretty and up-to-date Julia tutorials