TimSAstro

Hi, HN!

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.

I call Poe's law!

While I see what you're saying, I doubt you would claim to 'use' assembly when writing a C++ codebase - because (unless you're doing very low-level hand optimizations of the kind that get ever rarer), someone else has done the hard work of creating a compiler to do the translation for you. Same thing with NumPy et al, except one level higher up the abstraction stack.