MyST Markdown notebooks in the SciPy documentation

Hello, folks

A few months ago we discussed including the infrastructure to allow
notebook-style tutorials in the SciPy documentation. To avoid potential
problems with .ipynb files and version control/code review, as well as to
not require any storing of notebook outputs such as images, I put up a
proposal to use MyST-nb and Jupytext to allow executable markdown files in
our documentation.

After experimenting a bit, this now works:
https://github.com/scipy/scipy/pull/17322

I would like to ask for feedback both on the general idea and
implementation if you have any. The following are things to keep in mind:
1. There are two new docs dependencies added: myst_nb and jupytext.
2. The .md files added as part of this effort will be executed every time
the documentation is built from scratch. Right now there is only one such
file, but as the number of these files grows, so will the build time for
the docs. I believe this can be improved with caching of the executed
notebooks but I haven't implemented this here yet.
3.  An alternative is to have these notebooks stored in a separate repo.
NumPy does that (https://github.com/numpy/numpy-tutorials). The main con I
see in this case is that it may be hard to get people to contribute to this
second repo, as most folks will look for contributions to the main
scipy/scipy repo and not look beyond that, but it can be helped with some
"marketing" :)

Any feedback is welcome, here or in the PR itself.

Cheers,

Melissa

_______________________________________________
SciPy-Dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/scipy-dev.python.org/
Member address: [email protected]