[ANN] JuliaTutorialsTemplate

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.

Now, to solve this, I already announced here that I created PlutoStaticHTML.jl ([ANN] PlutoStaticHTML.jl) which solves many of the above problems.

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 :partying_face:

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

17 Likes