Make R code also execute when the jupyter-book is rendered

[monicathieu]

This issue is purely for back-end improvements.

As it stands (from how I set it up very quickly and dirtily during Neurohackademy 2022), every time edits are made to website content Markdown pages, a GitHub action spins up a small instance, equips it with the necessary Python packages, and then renders the whole jupyter-book. This runs any Python code in any of the Markdowns, ensuring the reproducibility of Python code examples by implicitly checking and confirming their runnability. The problem is, I only have that set up for Python code right now. The tutorials are all designed to be bilingual in R and Python, but as it stands, the R code is statically copied and pasted into code chunks that highlight the R code but don't actually run it. Each Markdown page can only have one kernel (I think), and I already knew how to set it up with a Python kernel, so that's the only supported kernel.

Ideally, the pipeline would look something like:

Executable sub-file with R code and outputs Executable sub-file with Python code and outputs

Both of those files are separately executed whenever the jupyter-book is rendered. Their code chunks and outputs are then injected into the bilingual tutorial page, ideally under different tabs in a tabset. This ensures that at some level, all code is being executed and checked when the book is rendered, AND that code is not copied and pasted (between the executed file and the tutorial file), reducing the possibility of accidental typos in tutorial file code that isn't actually run.

I still need to figure two big things to make this work:

1. How best can we inject code chunk text and outputs from R (and Python) executable files to the main tutorial Markdown?
2. How can we configure GitHub actions to run all R scripts and update code outputs when the book is rendered? I tried to start setting this up at Neurohackademy, but ran into issues with renv not successfully installing all the packages in the lockfile already associated with the project.

[monicathieu]

Taking notes on progress on this issue:

It seems like, no matter what happens, we'll likely have to switch the format away from one page per tutorial topic, with tabs for R and Python description/code. Sphinx tabs are added using a directive chunk, and executable code cells cannot be nested inside of other directive chunks.

Using the jupyter-book ToC subsection setup, we can group individual pages for the R and Python versions of tutorials in the ToC, which isn't as sleek, but will definitely still do the job. jupyter-book will render those individual pages! Sub-issue 1 taken care of.

Still stuck on sub-issue 2, though: getting jupyter-book to execute R code! Ugh! Even when files are saved as .Rmd and are converted using their suggested jupytext system, and I installed IRkernel so that jupyter would be able to run R, R code itself won't run! I'm pretty sure it's because wherever R is being started from via jupyter/IRkernel, it's not starting in the project folder and so isn't getting access to the renv-yoked packages. Why is package management SO HARD!?

[monicathieu]

Quick progress update for previous sub-issue 2:

The following steps appear to allow jupyter-book to execute R code (!!!):

1. Get IRkernel to work with renv: When IRkernel (or maybe any jupyter instance) is called, it is called in the working directory of the notebook file, not the project directory with the renv library. To circumvent this, add a .Rprofile file in each directory containing an Rmd to be jupy-fied with the commands setwd('../..') and source('renv/activate.R'), to replicate the functionality of the project-specific .Rprofile, but from the directory that it's actually getting called from. This will allow IRkernel to actually see renv-installed R packages.
2. Set the correct jupyter YAML headers: It should look like this:

   ---
   jupyter:
   kernelspec:
   display_name: R
   language: R
   name: ir
   ---

   ir is the default kernel name for the IRkernel. I think the display name can be anything, but jupytext specifically requires the language to be R in all-caps. I think technically jupyter itself is fine with lowercase or uppercase, but jupyter by default %% "magics" the language name at the beginning of each cell, which needs to be removed before running through R (because % is an illegal special command in regular R). The list of jupytext-recognized languages contains uppercase R, but not lowercase r, so I think that's why it wasn't getting caught properly in lowercase. Ugh!

Anyway, next step: getting GitHub Actions to run R and the IRkernel!