Try Literate.jl

[graeme-a-stewart]

We learned from @oschulz that BAT.jl use Literate.jl for their tutorial.

I wonder if we might try that for the tutorial? Jupyterbook is quite good, but not friction free. I also like the idea that people can access material as a notebook or a script. It will also make diffs a lot easier (we are in notebook hell with each commit and we probably need to start stripping all output away from the version controlled files (but it was useful to have it this time around, I think).

[Moelf]

Arguably Jupyter or Pluto are easier for interactively try change something and run. Literate is a script without notebook interface, unless one uses something like VSCode cell evaluation

[oschulz]

But Literate is easier to maintain, version control and test, since it's a valid Julia script. And it can easily be converted to a Jupyter notebook. The BAT tutorial, for example, is [written in Literate] syntax but rendered as part of the package docs and can be downloaded both as a script and a Jupyter notebook (see top of the linked page). Pluto notebook conversion isn't available in Literate so far, but it may be possible to using the Literate post-processing capability (with a bit of custom code).

[Moelf]

Introductory tutorials don't change that often, this doesn't evolve closely along any particular packages I think

[szabo137]

Hm, Pluto notebooks are valid Julia scripts, too, and they preserve the interactive behavior convenient for tutorials.

IMHO, Literate.jl is excellent for examples and How-tos, showcases with a clear task-answer structure and not much interaction.

[graeme-a-stewart]

One key issue is how to get a set of individual notebooks into a nice webpage that gives a whole overview. Jupyterbook does do a decent job of that. We have 16 individual notebooks at the moment (not counting exercise solutions). That can be done with Documenter.jl, but there is niceness in letting people use Binder (BTW, @Moelf do we know if anyone did that last week?).

One thing that made me tend to Jupyter was that it looked good on the GitHub site itself, but that's probably a specious argument as it needs the cell contents to be preserved, which is a git diff nightmare (we really need to strip cell outputs). Jupyter notebooks also run nicely in VS Code and so the barrier to entry is just that wee bit lower than with Pluto.

[Moelf]

BTW, @Moelf do we know if anyone did that last week?

don't have that metric I think. But yeah, Jupyter works well with Binder is definitely a plus for introductory material

[oschulz]

Jupyter works well with Binder is definitely a plus for introductory material

I wish we could make Google add official support for Julia to CoLab ...

[graeme-a-stewart]

OK, I think for now we stick to what we have as it's the lowest barrier to entry we can have. Later we can consider other options, should Binder/CoLab/etc. get better support for running the scripts/notebooks.

Thanks for the useful discussion!