3 ms·
Python developers: you can now make teaching tutorials in Jupyter notebooks and have them get automatically executed during the documentation build process and
by acidburnNSA 7y ago
Python developers: you can now make teaching tutorials in Jupyter notebooks and have them get automatically executed during the documentation build process and converted into theme-matching HTML by Sphinx with an extension [1]. I fired it up the other day and it's really glorious for tutorials. They're guaranteed to be up to date when you build the docs. Before that, I had a unit test that ran the tutorial with comments all over both the doc and the test that said YOU HAVE TO UPDATE THE OTHER IN SYNC!
[1] https://nbsphinx.readthedocs.io/ https://nbsphinx.readthedocs.io/
- AstralStorm 7y agoNot just Python, Jupyter has plenty of backends. Including C++. Word of warning though, you might be tempted to use the tutorial prototype style for an actual application. That doesn't work in general.
- closed 7y agonbsphinx is super handy! A cool tool to combine with it is jupytext, so you can keep your notebooks as rmarkdown files, which is a bit more human readable / GitHub editable. I did this with a recent library, siuba, and have not regretted it! https://github.com/machow/siuba/tree/master/docs https://github.com/machow/siuba/tree/master/docs