Allow .ipynb submissions of examples somehow?

[StanczakDominik]

This came up during PlasmaPy/PlasmaPy-Tutorials#16 and a bit during PlasmaPy/PlasmaPy-Tutorials#17. Basically, working with the sphinx-gallery .py file format is more painful than working with notebooks, and I think we need to do everything we can to ease the example submission process.

There are a few ways I see that we could take here:

• https://github.com/Chilipp/sphinx-nbexamples allows building examples from notebooks, but doesn't ease the fact that they're absolute pain to version control and review
• https://nbsphinx.readthedocs.io/en/0.4.2/ is another way of doing the same
• have a script that converts notebooks to .py once the PR is done, use it before merging example-adding PR - doesn't help with review, though that can be bypassed by simply pushing simple changes to notebooks instead of doing reviews (more or less limits example review to maintainers)
• maybe even have a bot that does that to every commit adding a new file to examples

Opinions, gentlefolks? 😃

Other things I have stumbled upon while searching:

• • https://blog.jupyter.org/integrating-output-in-documentation-with-jupyter-sphinx-ecf569ddab85 is a recent thing that lets you embed jupyter-executed blocks in sphinx docs, I'd like to try it but doesn't help us here
• https://sphinx-gallery.github.io/configuration.html#binder-links is pretty cool
  • https://github.com/mne-tools/mne-bids/pull/207/files is an implementation

[StanczakDominik]

also tagging @jhillairet for this discussion based on PlasmaPy/PlasmaPy-Tutorials#16 :

• https://www.reviewnb.com/ is a thing that looks pretty useful

Indeed dealing with notebook in github with plain text is not easy. An inconvenient of notebooks is that they rapidly increase the repository size. On scikit-rf, the good practice is to pull "empty" notebooks, for this reason of size. Then the html documentation is built with sphinx from the notebooks.

That's an interesting idea, I'll have to look into that...

[StanczakDominik]

scipy/scipy#5233 people have already had this discussion, it seems.

[StanczakDominik]

This got done in #792.