I just heard from @mwouts about this interesting patch/deploy of sphinx-gallery for building Binder links in Sphinx documentation. Here’s the blog post about it:
Sphinx-Gallery generates a collection of
.ipynb files for each example and creates a Binder link to point to it. However, this has the problem that you must host the documentation on gh-pages, not readthedocs. The PlasmaPy folks patch decided to utilize Jupytext so that, in Binder, their sphinx-gallery
.py files are automatically converted to
ipynb when the Binder session launches. This lets you host the documentation on readthedocs!
Looks interesting. Could you explain a bit why without this patch you have to host things on GH pages? I thought the way that sphinx-gallery works is to generate the notebooks when you build the HTML and then have a link to the repo in the “launch” badge at the bottom. Meaning where you host the built output shouldn’t matter?
Advert: scikit-learn now uses mybinder.org for their examples https://scikit-learn.org/dev/auto_examples/plot_anomaly_comparison.html#sphx-glr-auto-examples-plot-anomaly-comparison-py via sphinx-gallery (of course).
I’d like to add that the PlasmaPy gallery relies on Jupytext’s capacity to open Sphinx Gallery scripts directly as notebooks in Jupyter. No
.ipynb file is created at any point in this process. See for instance: when you click on the Binder link at the bottom of the Magnetostatic Fields example, Binder opens the script as a notebook in Jupyter. And that notebook… has a
Being able to open scripts or Markdown documents as notebooks on Binder is just a matter of adding
jupytext to the project (or Binder)'s requirement file. And if you want to state explicitly that all scripts should be treated as Sphinx Gallery scripts, and that you want the rST content to be converted to markdown, then you can add a
In the case of the scikit-learn repo, I think the challenge is the same, i.e. deploy Binder on the main repository, but the setup is a bit different. There, the
.ipynb files are created explicitly in
tl;dr on that is: “Because Sphinx-Gallery assumes it can link to a notebook that’s in a git repository somewhere, but if the gallery is built on ReadTheDocs, the generated notebooks will only be within the RTD-hosted website, not in a git repository”
@lesteve what do you think about adding a quick docs PR to sphinx-gallery to document the “build the notebooks in a
postBuild step so the links work” process? I’m happy to review a PR
Sorry I dropped the ball on this one.
Adding a PR in the sphinx-gallery doc seems a reasonable idea, although if I am being honest it feels a bit too hacky to be featured as an official work-around. I am afraid I am unlikely to do it in the short-term …
If people try the “no notebooks in the git repo but some notebooks in the docker image” (for lack of a better name, please suggest one …) a la scikit-learn approach and have questions/issues, more than happy to try help on this thread.
Since it hasn’t yet been mentioned in this discussion, I’d like to make some advertisement for my little Sphinx extension
It allows Sphinx to use Jupyter notebooks as source files.
It also enables support for any files that Jupytext can handle, see https://nbsphinx.readthedocs.io/en/0.5.1/custom-formats.html. I’m working on a concrete example in https://github.com/spatialaudio/nbsphinx/pull/408.
It also makes it easy to add Binder links, see https://nbsphinx.readthedocs.io/en/0.5.1/prolog-and-epilog.html.
And soon, it will also get its own gallery feature: https://github.com/spatialaudio/nbsphinx/pull/392.