Jupyter-book: Polyglot code blocks

[jedbrown]

I'm curious how one would go about writing a book in which the reader can choose a variant, say Python or Julia, for the code blocks. Could we teach MyST to process code-block variants, in which a single notebook contains multiple versions of code blocks, which we can execute separately with each kernel? So when building with a Python kernel, {code-block:julia} would be ignored, and vice-versa. Then we build one or more variants and provide cross-references.

[chrisjsewell]

You could consider using: https://vatlab.github.io/sos-docs/

[jedbrown]

Interesting project, though it seems to be about mixed-language workflows (where data needs to be passed between languages). I'm interested in the pedagogy, to maintain two versions of a book that use different programming languages. The use case that motivated me to open this issue is creating educational resources that did not lock instructors into a particular language choice (Python vs Julia). Most of the prose would be the same, but the code blocks and occasional admonitions would vary by language.

[choldgraf]

I think this would be a really interesting use-case to explore, though must admit I think it'll be a while before we get there. Much of Jupyter's infra assumes a "one language per notebook" model, and Thebe (which we use for on-page kernel execution) assumes basically the same thing.

[akhmerov]

jupyter-sphinx has some infrastructure in place for associating a different kernel with a different code cell (albeit not yet sufficient).

That, combined with something like sphinx-panels would achieve the desired result.

[chrisjsewell]

Multiple languages in a single file can be achieved with the SoS jupyter kernel, which IMO is a much more elegant solution than trying to construct multiple notebooks from a single file 😉

[chrisjsewell]

And yeh perhaps this could integrate with https://github.com/executablebooks/sphinx-panels/issues/28

[akhmerov]

Multiple languages in a single file can be achieved with the SoS jupyter kernel, which IMO is a much more elegant solution than trying to construct multiple notebooks from a single file

More elegant in which way? I imagine you still want to serve single language files to the users, you want to avoid the interaction between the kernels, and you don't want to expose consumers to extra machinery (e.g. needing to choose a subkernel when they create a new cell).

Due to the need to use panels, authoring this in notebook format isn't going to work anyway, since notebooks don't allow including code cells inside other directives (panels).

[chrisjsewell]

since notebooks don't allow including code cells inside other directives (panels).

This would be easily achievable in myst-nb via cell tags

[chrisjsewell]

SoS is better for actual polyglot files

If you only want two identical versions of the same notebook, with a different language. Then this is a slightly different use case and should be achieved by actually having two separate notebook files, with logic to "merge" them after execution within myst-nb or jupyter-book

[akhmerov]

This would be easily achievable in myst-nb via cell tags

Can you explain more? Cell tags don't control position of the code cells in the doctree, or am I missing something?

EDIT: for example, how to implement the following snippet using cell tags:

` {warning}
If you're crawling out of a cave, it's 2020 and you shouldn't anymore use
```{code-cell}
print "Hello world"

As you see, this just gives an error.

````

SoS is better for actual polyglot files

I agree.

If you only want two identical versions of the same notebook, with a different language. Then this is a slightly different use case and should be achieved by actually having two separate notebook files, with logic to "merge" them after execution within myst-nb or jupyter-book

That is fragile for the author because they now need to edit their work related to a single place in the output across multiple different files. Removing the need to do that is the biggest advantage of the EBP stack.

[jedbrown]

I agree that I really don't want two notebook files with "merge" logic. The sort of content I'm thinking of would be about 2/3 text and equations, 1/3 code. Perhaps it could be authored with SOS (with an extension to ensure that code blocks always come in pairs?) and have some ability to render it separately for each language (e.g., with a site-wide toggle). Rendering with panels might be useful for author/review, but less so for students trying to learn the content of the book. Panels (or a toggle that keeps place) could also be useful for someone familiar with the content of the book to learn another language (e.g., reader knows Python, wants to learn Julia).

[akhmerov]

Rendering with panels might be useful for author/review, but less so for students trying to learn the content of the book.

We're talking about something like this, wouldn't that be the representation you want? Or do you have something else in mind?

[jedbrown]

That's good for an author or reviewer, but too noisy for a student taking a class that just uses one language. I think a global toggle (in a sidebar, or just a different "version") would be better for a reader who just wants to learn the subject matter of the book.

[akhmerov]

Gotcha, so similar to https://documentation.mailgun.com/en/latest/api_reference.html

[jedbrown]

Yes (perhaps less prominent, but same idea).