[RFC] Single source material for Jupyter Notebooks/Data Carpentry Markdown

[jerdra]

With the requirement of Carpentries to use their markdown format and our preferred live teaching medium being Juypter Notebooks we've run into an issue of having to update the Carpentries MD and Jupyter Notebooks independently anytime an update is made to the lessons.

Tools like https://github.com/mwouts/jupytext enable automated Markdown/Notebook/Script generation from a single source file. However, an issue that we're running into is with the generation of data carpentry markdown tags.

This issue is to discuss ways in which we can integrate the data carpentry markdown tags into our future source format (possibly Jupytext MyST?)

[samwalkow]

Hi @jerdra, I have some experience with Jupytext, specifically with the notebook and markdown formats. I agree the MyST format could work. I can submit a PR with an working example?

Let me know if anything else would be helpful!

[jerdra]

Hi @samwalkow that'd be fantastic! My main worries were around trying to get the data carpentry style markdown tags integrated, if you have a potential solution for that i'd be more than interested in seeing it!

[samwalkow]

Got it! I’ve done some testing and have gotten several markdown tags to show up in a notebook, and vice versa. Are there any particular tags you are concerned about?

[jerdra]

Amazing!! Are you able to set up a pull request so that I could take a look and perhaps get a better look at what you have?

The main item that we were concerned about were the solutions/exercises tags and how they would be handled in the notebook.

A bit more detail:

If you take a look at the notebooks under _episodes/ you'll see that there are 2 types of notebooks. We have a *_solutions notebook and one without the suffix (workshop notebooks). The workshop is meant to be taught as a code-along with the *_solutions notebook serving to act as a guide for instructors and for students to catch-up if they fall behind.

Implementation-wise:

In the workshop notebook we'd like to ignore the solutions tag whereas in the solutions notebook we'd like to ignore the exercise tag. Let me know if that makes sense!

Thanks again for taking the initiative on handling this :)

[samwalkow]

Pull request submitted! Here it is: https://github.com/carpentries-incubator/SDC-BIDS-fMRI/pull/36

So, it is set up so that all changes in the notebooks are made in the markdown files, and vice versa. I have not figured out a way to ignore some tags depending on the situation. I'll keep looking though!