Merge guide and notebook

[ChristopherBrix]

I propose to merge the guide into the notebooks. Jupyter is able to render LaTeX and markdown, so we should not loose anything by doing so. And this way, we have one official version of code + explanations, without the risk of duplicating anything and differences between both versions.

For people that prefer to read a PDF, we can always convert the notebooks into a joint pdf afterwards (in the best case, this should be done automatically on every commit).

[ramon-astudillo]

thanks @ChristopherBrix, we talked about this other years. There is a lot of text in the guide and that can make using the notebook a bit cumbersome.

Having said that, code duplication and the consequent inconsistencies are a problem each year. @kepler and I have been talking about at least generating the exercises automatically both for the guide and the notebooks.

[ChristopherBrix]

But editing a large notebook wouldn't be much more complicated than editing the correct LaTeX files, right? Only reading it might be less convenient.

So maybe we could use a combination of tags (introduced in Jupyter 5) and nbconvert? We could have one large notebook per (sub)-chapter, which contains all the text from the guide, and all exercises. Then we can export everything to one huge guide pdf using nbconvert and a concatination of the generated chapter-pdfs. Those cells that contain information needed for the exercises could be given a specific tag. So a second run of nbconvert can select only those and create a new notebook only containing these specific cells. Then we could provide the students with both a single pdf, and a selection of lab notebooks. The big notebooks containing everything would only be needed to be edited by us.

[ChristopherBrix]

@ramon-astudillo Any thoughts on that? If you think it is worth a shot, I can try to implement it. I wanted to learn about git hooks anyway.

[ramon-astudillo]

Only reading it might be less convenient.

I think the guide serves various purposes and it is unclear how to disentangle them. At least we know that automatic workflows to maintain synchronicity between notebooks and guide are very much needed. We also need more stuff like synchronicity between master and student branches.

The one you propose replaces native latex compilation by latex compilation within a notebook, are you sure we get the same quality?. @kepler and I discussed using place-markers (e.g. \input{exercise_1_1.tex}) in the original latex code and generate the text code from the notebooks.

another option is total separation of exercises and guide, leaving the guide more as a collection of tutorials on the formal principles with exercise place markers.