Jupyter Notebooks sind großartig, wenn es darum geht, Code zu schreiben und ihn zu dokumentieren. In diesem Beitrag erkläre ich, wie sie sich in Blogs einbinden lassen.
Jupyter Notebooks setzen das sogennante literate programming um. Der Begriff geht auf Donald Knuth zurück, der nicht zuletzt als Entwickler des TeX-Systems in die Geschichte der Informatik eingegangen ist.1 Die Idee hinter dem literate programming ist, dass der Programmcode, den die Maschine interpretiert, ausgiebig kommentiert und dokumentiert wird, sodass ein menschlicher Leser das Programm wie einen ‘literarischen’ Text lesen kann. Knuths Anliegen war es also, Programme zu schreiben, die Menschen genauso gut gelesen können wie Computer.
Mit Jupyter Notebooks ist genau das möglich: Man kann Code schreiben und ihn mit Markdown oder LaTeX dokumentieren. Besonders praktisch ist dabei, dass ein Notebook auch die Ausgabe und Rückgabewerte des Codes darstellt.2 Auf diese Weise ist es nicht nur möglich, komplexe Programme zu verfassen und ansprechende Graphiken in des Notebook einzubinden. Es macht ebenfalls die Schritte, die zu ihrer Erstellung geführt haben, transparent und nachvollziehbar.
Notebooks können ohne allzuviel Aufwand in andere Formate wie Markdown, LaTeX, PDF oder HTML exportiert werden. Trotzdem ist es nicht einfach, sie auf diese Weise in eine bestehende Seite zu integrieren. Dafür sind nämlich umfangreiche Anpassungen des CSS nötig. Außerdem kann es vorkommen, dass beispielsweise die Ausgaben des Codes wegfallen. Es gibt zahlreiche Erfahrungsberichte, deren Fazit darin besteht, dann doch gleich einen Blog zu schreiben und die Code-Schnipsel aus dem Notebook von Hand zu übernehmen.
Besser wäre es aber, wenn man ein fertiges Notebook komplett in eine Seite integrieren könnte, ohne die beiden Darstellungssysteme ineinander überführen zu müssen. Hier helfen Gists weiter!
Ein Gist ist ein Ablageplatz für Code. Github stellt sie zum Beispiel bereit. Im Unterschied zu einem klassischen Repositorium legt man keine Dateien ab, sondern tatsächlich nur Code-Schnipsel. Den Link zum Gist kann man teilen und weitergeben. Praktisch daran ist, dass Github je nach Endung, die man dem Gist gibt, Syntax-Highlighting und dergleichen anbietet.
Um besonders komfortable Gists aus seinen Dateien zu erstellen, bietet sich das Ruby Gem gist an. Mit seiner Hilfe lassen sich nicht nur die Login-Daten für Github speichern, sondern auch Gists erstellen, aktualisieren, löschen und so weiter.
Der Clou an Gists ist, dass sie dank JavaScript unproblematisch in nahezu jede Seite eingebunden werden können. Das erreicht man durch einen Tag der Form:
<script src="https://gist.github.com/USER/GIST-TAG.js"></script>
Man erhält es beispielsweise auf der entsprechenden Gist-Seite von Github. Es ist auch möglich, durch gist -e <FILENAME ein Gist aus der Datei FILENAME zu erstellen und dann anschließend den Tag in die Zwischenablage zu kopieren.
Für Benutzer von Jekyll gibt es das Plugin jekyll-gist. Mit ihm bindet man ein Gist über die folgende Zeile ein:
{% gist GIST-TAG %}
Falls nun der Code eines fertig formatierten Notebooks in dem Gist eingetragen ist, kann man es elegant in seinen Blog einfügen.
Der inzwischen zum Klassiker avancierte Aufsatz von Knuth, Donald: „Literate Programming“, in: The Computer Journal 27/2 (1984), S. 97–111. ↩