Is it possible to make the notebooks executable?

[robertodr]

Is it possible to make the notebooks executable?

[rkdarst]

Once I tried that with sphinx-lesson, and it worked basically with no extra work. Add the extension to your requirements.txt and conf.py, any necessary configuration locally. We should document how to do it and possibly put template code in there. Want to give it a try, and see if it still works?

[robertodr]

Thanks! Yes, I'll try it out (later today) and report. I'll add documentation on how to do it.

[robertodr]

Not much luck. https://github.com/ENCCS/veloxchem-workshop/blob/master/content/conf.py jupyter-book wants to read toc.yml and I'm not sure how to convince it not to do that :/

[rkdarst]

I think this is the underlying tool that actually makes it work: https://sphinx-thebe.readthedocs.io/en/latest/ I seem to have some commits in there, so I must have found it at some point... I can't see how but I imagine that instead of using the container block, there was some way to configure the HTML classes that would get enabled, and set that to the actual kinds of code blocks we had. Perhaps we can add a setting that will add the right classes to the blocks that would be relevant to thebe.

[robertodr]

sphinx-thebe would work, but I'd need to write the whole content in rst. I wanted to keep the ipynb files separate, such that they could be reused separately from the lesson. I need to dig a bit deeper.

[rkdarst]

Can you send me the lesson so I can play around with it some myself? I have a feeling it should be possible but don't know enough to give any specific advice...

[robertodr]

Here it is: https://github.com/ENCCS/veloxchem-workshop I've managed to add a cell on the main page and it works. But the notebook in the "First VeloxChem calculation" is static.

[rkdarst]

I looked more and here is my analysis (at first I didn't realize the difference between running the full notebook and cells in the page): - sphinx-thebe does the per-cell thing, when cells are tagged with a certain class. - The "launch on binder" button, like we see on this page (at the top, the rocket icon): https://jupyterbook.org/interactive/launchbuttons.html is just a normal Binder link, that goes to mybinder.org. It seems that sphinx-book-theme has support that combines the a) repository_url b) filename c) possible launching services to make that button. But, there is nothing really special about this. For now, I would create my own "launch on binder" link, and either put that in the page or on the frontpage of the lesson. - One third option could be "thebe to run every code cell in the rendered .ipynb html page, straight from the page (no redirect to binder)". But then you don't have things like making new cells, saving it, etc. But you don't have to leave the page. Is this useful? Does this match what you think? And I understand you would like the second one. I could look into adding some sort of theme support, but unlike that we don't assume that every page is an .ipynb file so that it "just works". Perhaps I could also make some sort of "launch on binder" directive (.. launch-button::) that would add a launch button to that very page. What do you think is the right balance of complexity and usefulness here? Or even the simpler question: what do you need for your course, right now?

[robertodr]

Thanks for taking the time to look into this!

What I would like to achieve I would like to be able to use the Sphinx website as I would other lessons without interactive content, while being able to execute the cells without the need to share another browser tab. I feel this would be more engaging for the audience, since they can execute cells at the same time as I do and tinker around without losing (too much) focus on what I am sharing.

1. Just using sphinx-thebe would be enough. But that requires that one works on the content of the executable cells separately and once that work is converged, copy-pastes them in markdown or restructuredtext.
2. Adding the button "by hand" is no problem and, in fact, was the first thing I was going to do, before remembering about executable book. It would be great if the launch binder button could be added to sphinx-lesson through parameters in conf.py.
3. Third option is useful to not duplicate effort between developing the notebook and developing the lesson.

For my use case, I think I need 2+3: execute cells within the lesson, but provide an "escape hatch" to the mybinder.org instance behind it.

[robertodr]

And by the way, the course will take place in 3 months. I started setting it up early because there's a few moving parts I need to figure out (running quantum chemical calculations, visualizing molecules, and molecular orbitals)

[robertodr]

OK, it seems using sphinx-book-theme does exactly what I want out of the box. I can write the content as notebooks and the theme will take care of rendering it and providing the launch buttons: https://enccs.github.io/veloxchem-workshop/ I've configured two buttons: to redirect to MyBinder or to start Thebe. What remains to be fixed is the styling of custom directives, which is somewhat related to #45.

[rkdarst]

I think that matched what I saw: somehow, the theme would label everything on the whole-page level. I think that someone clever enough with javascript could probably get the same effect, but I'm not sure when I would get to it. Is that theme compatible enough to recommend in general for this use case?

[rkdarst]

With sphinx_rtd_theme I was able to make a whole notebook executable:

• start from a Jupyter notebook (thus it needs myst, not rst)

• add config
  `extensions.append('sphinx_thebe')
  This config makes it detect output and link it properly, you could do other things depending on your interest:

   "selector": "div.cell",
   "selector_input": "div.cell_input",
   "selector_output": "div.cell_output",
   }
  

• Add a launch button to a cell:

   ```{thebe-button}
   ```
  

• Every cell in the notebook becomes executable

• Other config likely needed, both in the page metadata and in the conf.py (setting kernels, repos to launch, etc): https://sphinx-thebe.readthedocs.io/en/latest/configure.html

... perhaps still need some debugging. (And in case of difficulties, I used the latest unreleased version of sphinx_thebe, but I think that shouldn't matter. However, somehow sphinx-autobuild didn't work with it, I didn't have time to figure out why...)