8 ms·

Executable Tutorials

73 points by dharmatech 5y ago

pugio 5y ago
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`. 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. Admittedly this only captures a piece of what'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. Very nice ideas in this article, thanks!
- dharmatech 5y ago
  Thanks for reading it and for your comments. Are the Jupyter notebooks that you refer to available publicly?
Glench 5y ago
Relevant: http://worrydream.com/ExplorableExplanations/ http://worrydream.com/ExplorableExplanations/ One piece of my work in this area: https://glench.github.io/fuzzyset.js/ui/ https://glench.github.io/fuzzyset.js/ui/
- dharmatech 5y ago
  Wow, I feel like posting to HN was worth it just to learn about your project alone. Thanks for sharing!
cdaringe 5y ago
Related, I recently cut "markdown_player@v1.2.0 | Deno" https://deno.land/x/markdown_player@v1.2.0 https://deno.land/x/markdown_player@v1.2.0 , but ocaml mdx lib seems to be likely more capable.
- dharmatech 5y ago
  Wow, this is very cool. Thank you for sharing!
- __mharrison__ 5y ago
  Isn't this like doctest in Python? My slides and books are all "executable". I write them in restructured text and have tooling to either execute the code or build the output (in pdf, epub, mobi, slides).
__mharrison__ 5y ago
(I do a lot of corporate training in DS/ML and Python) I've got an example of doing this in Jupyter. The repo is here [0] 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/labs from the Python script and then go back to notebooks. (Python/text is easier than working with JSON/notebook format.) When I teach Python I don'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't complain. They can use any editor they want, and then just run the tests to validate. I'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. I'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. Would be curious to see what you build. 0 - https://resources.oreilly.com/binderhub/beginning-supervised-machine-learning-with-python https://resources.oreilly.com/binderhub/beginning-supervised...
- truth_ 5y ago
  Have you looked into nbdev?
  - __mharrison__ 5y ago
    This is something I still need to do.
- nonameiguess 5y ago
  You might consider R Markdown and knitr, which have supported Python and many other languages besides R for a long time, but the templates are stored as plain text rather than the terrible .ipynb format, and render to both html and pdf and support LaTeX. The developer's book shows how to do it: https://bookdown.org/yihui/rmarkdown-cookbook/eng-python.html https://bookdown.org/yihui/rmarkdown-cookbook/eng-python.htm...
tomashubelbauer 5y ago
I'm exploring something along these lines in my (now mostly dormant) project called MarkRight: https://github.com/tomashubelbauer/markright https://github.com/tomashubelbauer/markright 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 "running" the MarkRight document are artifacts (the source code, the compiled executables, graphics etc.), but the document is a single source of truth. Examples: https://github.com/TomasHubelbauer/markright/edit/master/example/feature-showcase/readme.md https://github.com/TomasHubelbauer/markright/edit/master/exa... 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.
- nerdponx 5y ago
  Sounds like R Markdown [0], a descendant of Knuth's WEB system and language [1]. But so do the OP and many of the other projects being posted here. 0: https://rmarkdown.rstudio.com/ https://rmarkdown.rstudio.com/ 1: https://mirror.las.iastate.edu/tex-archive/info/knuth/webman.pdf https://mirror.las.iastate.edu/tex-archive/info/knuth/webman...
- dharmatech 5y ago
  Amazing project. Checking out the MarkRight examples now. Love all the features you offer from the convenience of markdown.
- dharmatech 5y ago
  The node-cli-example is nice!
cppwithprojects 5y ago
We built a C++ project-based course [0] that uses exactly the same ideas. 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. 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. 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. We are thinking about writing a blog post about this if there's interest! 0: https://learncppthroughprojects.com https://learncppthroughprojects.com
- dharmatech 5y ago
  Very impressive. Let us know if you publish more about your process.
Daub 5y ago
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.
noworld 5y ago
Is it pronounced ex-EC-utable or exe-CUT-able?
- zimpenfish 5y ago
  I think British pronunciation would be "ecksy-cute-able".
  - nerdponx 5y ago
    AmE also generally emphasizes the third syllable.
plondon514 5y ago
I’m building https://codeamigo.dev https://codeamigo.dev which only works with JS/TS atm but the goal is to support many more languages. Love the idea of executable tutorials written by the community.
yugene 5y ago
An article on literate programming with Org-mode for beginners: https://www.offerzen.com/blog/literate-programming-empower-your-writing-with-emacs-org-mode https://www.offerzen.com/blog/literate-programming-empower-y...
mridsole 5y ago
I'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'm not a big fan of Jupyter's GUI editors for notebooks (and all the usual issues with .ipynb's under version control), but Jupytext is great and works quite well with Jupyter Book. 0: https://jupyterbook.org/intro.html https://jupyterbook.org/intro.html

73 points by dharmatech 5y ago

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`. 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. Admittedly this only captures a piece of what'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. Very nice ideas in this article, thanks!

dharmatech 5y ago
Thanks for reading it and for your comments. Are the Jupyter notebooks that you refer to available publicly?

Glench 5y ago

Relevant: http://worrydream.com/ExplorableExplanations/ http://worrydream.com/ExplorableExplanations/ One piece of my work in this area: https://glench.github.io/fuzzyset.js/ui/ https://glench.github.io/fuzzyset.js/ui/

dharmatech 5y ago
Wow, I feel like posting to HN was worth it just to learn about your project alone. Thanks for sharing!

cdaringe 5y ago

Related, I recently cut "markdown_player@v1.2.0 | Deno" https://deno.land/x/markdown_player@v1.2.0 https://deno.land/x/markdown_player@v1.2.0 , but ocaml mdx lib seems to be likely more capable.

dharmatech 5y ago
Wow, this is very cool. Thank you for sharing!
__mharrison__ 5y ago
Isn't this like doctest in Python? My slides and books are all "executable". I write them in restructured text and have tooling to either execute the code or build the output (in pdf, epub, mobi, slides).

__mharrison__ 5y ago

(I do a lot of corporate training in DS/ML and Python) I've got an example of doing this in Jupyter. The repo is here [0] 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/labs from the Python script and then go back to notebooks. (Python/text is easier than working with JSON/notebook format.) When I teach Python I don'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't complain. They can use any editor they want, and then just run the tests to validate. I'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. I'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. Would be curious to see what you build. 0 - https://resources.oreilly.com/binderhub/beginning-supervised-machine-learning-with-python https://resources.oreilly.com/binderhub/beginning-supervised...

truth_ 5y ago
Have you looked into nbdev?
- __mharrison__ 5y ago
  This is something I still need to do.
nonameiguess 5y ago
You might consider R Markdown and knitr, which have supported Python and many other languages besides R for a long time, but the templates are stored as plain text rather than the terrible .ipynb format, and render to both html and pdf and support LaTeX. The developer's book shows how to do it: https://bookdown.org/yihui/rmarkdown-cookbook/eng-python.html https://bookdown.org/yihui/rmarkdown-cookbook/eng-python.htm...

tomashubelbauer 5y ago

I'm exploring something along these lines in my (now mostly dormant) project called MarkRight: https://github.com/tomashubelbauer/markright https://github.com/tomashubelbauer/markright 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 "running" the MarkRight document are artifacts (the source code, the compiled executables, graphics etc.), but the document is a single source of truth. Examples: https://github.com/TomasHubelbauer/markright/edit/master/example/feature-showcase/readme.md https://github.com/TomasHubelbauer/markright/edit/master/exa... 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.

nerdponx 5y ago
Sounds like R Markdown [0], a descendant of Knuth's WEB system and language [1]. But so do the OP and many of the other projects being posted here. 0: https://rmarkdown.rstudio.com/ https://rmarkdown.rstudio.com/ 1: https://mirror.las.iastate.edu/tex-archive/info/knuth/webman.pdf https://mirror.las.iastate.edu/tex-archive/info/knuth/webman...
dharmatech 5y ago
Amazing project. Checking out the MarkRight examples now. Love all the features you offer from the convenience of markdown.
dharmatech 5y ago
The node-cli-example is nice!

cppwithprojects 5y ago

We built a C++ project-based course [0] that uses exactly the same ideas. 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. 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. 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. We are thinking about writing a blog post about this if there's interest! 0: https://learncppthroughprojects.com https://learncppthroughprojects.com

dharmatech 5y ago
Very impressive. Let us know if you publish more about your process.

Daub 5y ago

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.

noworld 5y ago

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

zimpenfish 5y ago
I think British pronunciation would be "ecksy-cute-able".
- nerdponx 5y ago
  AmE also generally emphasizes the third syllable.

plondon514 5y ago

I’m building https://codeamigo.dev https://codeamigo.dev which only works with JS/TS atm but the goal is to support many more languages. Love the idea of executable tutorials written by the community.

yugene 5y ago

An article on literate programming with Org-mode for beginners: https://www.offerzen.com/blog/literate-programming-empower-your-writing-with-emacs-org-mode https://www.offerzen.com/blog/literate-programming-empower-y...

mridsole 5y ago

I'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'm not a big fan of Jupyter's GUI editors for notebooks (and all the usual issues with .ipynb's under version control), but Jupytext is great and works quite well with Jupyter Book. 0: https://jupyterbook.org/intro.html https://jupyterbook.org/intro.html