TuringLang/docs

Ease review by using assertions

Opened this issue · 1 comments

The post on https://discourse.julialang.org/t/package-growth-tips-and-tricks-creating-an-organization-triage-better-management/65167/2 got me thinking about the current setup of TuringTutorials.

The tutorials are now very fragile because:

  • the tutorials aren't tested and
  • the tutorial build logic isn't tested.

For example, Weave could change in such a way that errors aren't correctly recognized by the build. This makes reviewing in the train impossible (see the aforementioned post).

The solution would be to add more tests for the build logic and add assertions in the tutorials.

I'm assigning this issue to myself, but others are, of course, also welcome to pick it up.

  • Add tests to build logic
  • Add test to verify that build fails if assertion doesn't hold
  • Add assertions to tutorial 00 - introduction (#278)
  • Add assertions to tutorial 01 - gaussian mixture model (#276)
  • Add assertions to tutorial 02 - logistic regression (#248)
  • Add assertions to tutorial 03 - bayesian neural network
  • Add assertions to tutorial 04 - hidden markov model
  • Add assertions to tutorial 05 - linear regression (#277)
  • Add assertions to tutorial 06 - infinite mixture model
  • Add assertions to tutorial 07 - poisson regression
  • Add assertions to tutorial 08 - multinomial logistic regression
  • Add assertions to tutorial 09 - variational inference (#249)
  • Add assertions to tutorial 10 - bayesian differential equations

I also think we should put assertions in hidden cells unless they are of interest to the reader.