Makefile for generating Jupyter Book and figures

[CasparJungbacker]

@rlanzafame and I have discussed the best way to include code that produces figures in the Jupyter Book. The new workflow is described in recipes.md. To accommodate this workflow, I made a Makefile that generates the figures and the Jupyter Book itself. The command for testing the book is also included in there.

Features:

• make figures looks for any Python source code in the code/ directory, executes it, and places the generated figures in the figures/ directory.
• make book generates all figures first, and then build the Jupyter Book. Due to the nature of Make, it only executes when any of the Jupyter Notebooks, Markdown files, or figure source code has changed.
• make clean removes any generated files.
• make test builds the Jupyter Book with the flags -n (nit-picky mode) and -W (warnings are errors).

[review-notebook-app[bot]]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[rlanzafame]

besides the one comment above, this looks great! Next step I will replace a few figures with the code so that there is a working example in the book.

[CasparJungbacker]

@CasparJungbacker i was thinking about why the .svg files are removed in the cleaning step. Let me know if the following is correct: .py files create the figure, which makes .svg file in figures directory. Then when the book is built all figures are also included in the HTML source (_build directory), so there is no reason to duplicate them since the .svg files in the HTML dir will remain as-is as long as there is no change to the *.py file that generated it.

Yeah you're right. On your local machine, if you don't run make clean, Make does not rebuild the figures in between Jupyter Book builds. In between pipelines, figures are not preserved in the figures directory, but they are cached in the _build directory (but Make is not aware of this). This is not a huge problem right now, since building figures does not form the majority of the building time as we do not have a lot of them. There should be some way to edit the Makefile so that it's aware of the _build directory. I'll make an issue out of this for the future 👍