Executable Tutorials

(I do a lot of corporate training in DS&#x2F;ML and Python)<p>I&#x27;ve got an example of doing this in Jupyter. The repo is here [0]<p>I generate the repo using a combination of Jupytext to convert the completed notebooks (with the labs done) to python scripts and code to remove the homework&#x2F;labs from the Python script and then go back to notebooks. (Python&#x2F;text is easier than working with JSON&#x2F;notebook format.)<p>When I teach Python I don&#x27;t use Jupyter. I use unittest code. The labs are contained in the tests and if the students follow directions, the tests will pass and won&#x27;t complain. They can use any editor they want, and then just run the tests to validate.<p>I&#x27;ve thought about building tooling (in Python) to automate code creation in both editors (for Python) and Jupyter (for data science) like you suggest. I have a repo sitting around my computer where I started automating the browser but ... there is not enough time in the day.<p>I&#x27;ve even thought about teaching via Twitter (this is kind of wierd and might make a fun conference gimmick). But I also have tooling to take md-like content consisting of prose, images, and code, and automate posting to Twitter. Then I could hit a button and instead of going to the next slide, I post the next tweet.<p>Would be curious to see what you build.<p>0 - <a href="https:&#x2F;&#x2F;resources.oreilly.com&#x2F;binderhub&#x2F;beginning-supervised-machine-learning-with-python" rel="nofollow">https:&#x2F;&#x2F;resources.oreilly.com&#x2F;binderhub&#x2F;beginning-supervised...</a>

Relevant: <a href="http:&#x2F;&#x2F;worrydream.com&#x2F;ExplorableExplanations&#x2F;" rel="nofollow">http:&#x2F;&#x2F;worrydream.com&#x2F;ExplorableExplanations&#x2F;</a><p>One piece of my work in this area: <a href="https:&#x2F;&#x2F;glench.github.io&#x2F;fuzzyset.js&#x2F;ui&#x2F;" rel="nofollow">https:&#x2F;&#x2F;glench.github.io&#x2F;fuzzyset.js&#x2F;ui&#x2F;</a>

We do something similar for our teaching materials. All lessons are in Jupyter notebooks, as well as cells with inline unit tests, marked with the special comment `# HIDE CELL`.<p>A build script then runs the full notebook along with tests, and strips out cells (or pieces of a cell) which contain these magic comments.<p>Admittedly this only captures a piece of what&#x27;s discussed in the article. Perhaps in the future will construct our videos directly from the notebooks as well, with other special comments containing the relevant pieces of script as well as where the camera should be centered. Then we can generate the notebooks and the visuals automatically, and just send an email to the voiceover person to re-record any script changes.<p>Very nice ideas in this article, thanks!

We built a C++ project-based course [0] that uses exactly the same ideas.<p>The core of our approach is that every code snippet is extracted from a fully working codebase and every code iteration is tracked in git.<p>We unit-test each commit, which means that every tutorial step works. Also, making a change in an early code iteration requires a proper git rebase, with the change propagating through history without conflicts.<p>We also annotate the code to extract snippets, and then run scripts to autogenerate git diffs for those snippets. The scripts also output the unannotated version of the codebase, which we share with the course participants.<p>We are thinking about writing a blog post about this if there&#x27;s interest!<p>0: <a href="https:&#x2F;&#x2F;learncppthroughprojects.com" rel="nofollow">https:&#x2F;&#x2F;learncppthroughprojects.com</a>

I&#x27;m exploring something along these lines in my (now mostly dormant) project called MarkRight: <a href="https:&#x2F;&#x2F;github.com&#x2F;tomashubelbauer&#x2F;markright" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;tomashubelbauer&#x2F;markright</a><p>The idea is that for didactic resources (be it documents, tutorials or even small pieces of software), your prose and code are both included in a MarkDown file and fenced code blocks are used to designate creation, altering and deletion of files. Other files that get created when &quot;running&quot; the MarkRight document are artifacts (the source code, the compiled executables, graphics etc.), but the document is a single source of truth.<p>Examples: <a href="https:&#x2F;&#x2F;github.com&#x2F;TomasHubelbauer&#x2F;markright&#x2F;edit&#x2F;master&#x2F;example&#x2F;feature-showcase&#x2F;readme.md" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;TomasHubelbauer&#x2F;markright&#x2F;edit&#x2F;master&#x2F;exa...</a><p>I recommend still keeping those in version control for online viewing in GitHub. I have not built anything cool with MarkRight yet, but I think the idea has potential. Curious what others think.

An article on literate programming with Org-mode for beginners: <a href="https:&#x2F;&#x2F;www.offerzen.com&#x2F;blog&#x2F;literate-programming-empower-your-writing-with-emacs-org-mode" rel="nofollow">https:&#x2F;&#x2F;www.offerzen.com&#x2F;blog&#x2F;literate-programming-empower-y...</a>

Related, I recently cut &quot;markdown_player@v1.2.0 | Deno&quot; <a href="https:&#x2F;&#x2F;deno.land&#x2F;x&#x2F;markdown_player@v1.2.0" rel="nofollow">https:&#x2F;&#x2F;deno.land&#x2F;x&#x2F;markdown_player@v1.2.0</a> , but ocaml mdx lib seems to be likely more capable.

Semi related... the 3d sculpting software ZBrush used to have interactive demos within the software powered by its own scripting language. Very helpful. Placed the help exactly where it was needed.

I&#x27;ve been using Jupyter Book [0] at work to put together a cookbook for a market data analysis package, and am really liking it so far. I&#x27;m not a big fan of Jupyter&#x27;s GUI editors for notebooks (and all the usual issues with .ipynb&#x27;s under version control), but Jupytext is great and works quite well with Jupyter Book.<p>0: <a href="https:&#x2F;&#x2F;jupyterbook.org&#x2F;intro.html" rel="nofollow">https:&#x2F;&#x2F;jupyterbook.org&#x2F;intro.html</a>

I’m building <a href="https:&#x2F;&#x2F;codeamigo.dev" rel="nofollow">https:&#x2F;&#x2F;codeamigo.dev</a> which only works with JS&#x2F;TS atm but the goal is to support many more languages. Love the idea of executable tutorials written by the community.

Is it pronounced ex-EC-utable or exe-CUT-able?