Author here. A friend mentioned this was on the front page so I wanted to stop by and make explicit that this advice is OUT OF DATE as far as I'm concerned. It's way too much hassle (I work in a much larger team now than I did then!) and doesn't play well with rebase etc.
These days I either recommend the jupytext approach (not tried it but seems sensible) or personally I just use Sphinx-gallery.
Advantages:
* Plain python files play well with IDE refactoring, Black formatter, etc etc.
* You now have a readymade 'tutorial' page for your docs.
* Files are run with every docs build, so you can configure things to alert you when they're broken.
Disadvantages:
* You end up editing a throwaway notebook file. If you forget to copy-paste your edits back to the source, and rebuild, you have lost your edits. However, this forces me to keep the 'temporary, exploratory' nature at the front of my mind and not allow the notebook code to grow too large before performing some clean-up.
Author here. A friend mentioned this was on the front page so I wanted to stop by and make explicit that this advice is OUT OF DATE as far as I'm concerned. It's way too much hassle (I work in a much larger team now than I did then!) and doesn't play well with rebase etc.
These days I either recommend the jupytext approach (not tried it but seems sensible) or personally I just use Sphinx-gallery.
Advantages:
* Plain python files play well with IDE refactoring, Black formatter, etc etc.
* You now have a readymade 'tutorial' page for your docs.
* Files are run with every docs build, so you can configure things to alert you when they're broken.
Disadvantages:
* You end up editing a throwaway notebook file. If you forget to copy-paste your edits back to the source, and rebuild, you have lost your edits. However, this forces me to keep the 'temporary, exploratory' nature at the front of my mind and not allow the notebook code to grow too large before performing some clean-up.