Making docstring examples interactive

Contributor & Development Discussion
1

Is anyone else working on or interested in interactive documentation?

I’ve spent a little time working out ways to add some interactivity to SciPy’s Sphinx documentation. I’ve toyed around with using jupyterlite-sphinx a Sphinx extension which makes it easy to embed JupyterLite notebooks in documentation. For anyone unaware, these notebooks run in browser.

Though jupyterlite-sphinx is easy to use and works well, if you want to embed a notebook in a page, you need to link to an actual notebook file that’s contained in your docs sources. Since it would be tedious to create these notebooks for all of SciPy and we already have a lot of Examples sections in the docstrings, I hit upon the idea of writing a Sphinx extension which can convert an Examples sections into a notebook at build time and embed this using JupyterLite.

I’ve created a rough prototype here: GitHub - steppi/sphinx-try-examples: Adds ability to try out docstring examples in an interactive jupyterlite notebook.. You can find it deployed for a toy example here, Example Package API — example_package v0.0.0 Manual; and the repo where this is deployed from is here, GitHub - steppi/interactive_doc_experiments: Experiment with interactive documentation for Python projects.

If you scroll to the Examples section, you’ll see a little button underneath the rendered example snippet that says Try it!. If you press the button, the examples snippet should change in-place to an embedded notebook.

I just wanted to make others aware of what I’ve been working on. I’d be interested if anyone has any feedback, perhaps regarding the plan to generate notebooks from docstring Examples sections, whether the prototype implementation might have obvious flaws I’ve missed, whether there might be a better way to go about things here, or just anything that comes to mind.

Some things I’m already aware of:

  • sphinx-try-examples is not a great name. In the past I’ve had a tendency to dwell on names too long before getting down to work, so just came up with a quick working title.
  • The button is ugly. I’m not a front-end developer or even a web developer. This is just a prototype to show the intended behavior.
  • It would be good to be able to switch back and forth between the rendered examples and the embedded notebook.

As this moves forward, I plan to try to get help from a front-end developer. Perhaps as this becomes more polished, it could be incorporated into the jupyterlite-sphinx extension if there’s interest on that side.

6 Likes
2

This looks great!
One quick question: the example uses prebuilt scipy, is this right? So this can in principle be deployed today , for released scipy versions, as long as the pyodide build of scipy is somewhat manual (not that I’m seriously suggesting doing that, it’s more of a thought).

3

Thanks Evgeni! Yes this could be deployed immediately if we wanted.

4

Actually, I need to check to make sure. I know that scikit-learn is using jupyterlite in their docs, so assumed it should be straightforward to make work, but I’m not sure yet what it actually took on their part.

5

I’ve deployed this for all of Scipy’s docs here, SciPy documentation — SciPy vv1.11.2-try-examples Manual. It could still use a little polishing, but I managed to fix quite a few small issues that popped up and all of the generated notebooks I’ve checked so far look good now. There probably are still some weird edge cases I haven’t handled yet though.

This is using the prebuilt SciPy that currently ships with Pyodide. I branched off of v1.11.2 on my fork to do this, so that the SciPy versions would match up.

I plan to PR this to Jupyterlite-Sphinx today.

1 Like