Aangepaste templates voor Jupyter Notebooks met Jinja2

In data science moet je vaak rapporten maken van je werk om te laten zien aan beslissers of andere niet-technische collega’s. Je Jupyter Notebook omzetten naar een stabiel PDF- of HTML-document is makkelijker deelbaar met collega’s die geen Python of Jupyter hebben geïnstalleerd. Python gebruikt een bibliotheek genaamd nbconvert en een templatingtaal genaamd Jinja2 om documenten te converteren. Templates bepalen hoe een document wordt weergegeven op een webpagina of in een ander outputformaat. Begrijpen hoe je templates kunt aanpassen helpt om je Notebooks om te zetten in fraai vormgegeven rapporten.

Jupyter Notebooks zijn een manier om Python-code in je browser uit te voeren. Wil je meer leren over Python, bekijk dan zeker onze gratis cursus Intro to Python for Data Science.

In deze tutorial komen de volgende onderwerpen aan bod:

• Templates en de Jinja2-templatedesigner.
• Rendering van templates en overerving.
• Hoe je nbconvert gebruikt om je Notebooks te exporteren.
• De syntaxis en structuur om de standaard Jupyter-templates voor HTML-export uit te breiden.
• De verschillen bij exporteren naar LaTeX- en PDF-formaten.

Wat zijn templates?

Van de Python-wiki: "Templating, en specifiek webtemplating, is een manier om data in verschillende vormen weer te geven... Vaak gaat een templatingoplossing uit van een document (de template) en data. Templates lijken meestal sterk op de uiteindelijke output, met placeholders in plaats van echte data"

De Jupyter Notebook kan eenvoudig worden geëxporteerd via File -> Download As (in Jupyter Lab zie je Export Notebook As). Deze optie gebruikt de standaardtemplates die in de hoofdomgeving van Jupyter staan. Jinja2 is een krachtige templatingtaal voor Python om blokken en opmaak te definiëren. Templates hebben secties, gedefinieerd door tags, die aangeven hoe de template de invoerdata moet renderen. De data vervangt de variabelen, of expressies, wanneer de template wordt gerenderd.

De delimiters voor de verschillende secties van een template zijn:

• {% ... %} voor statements
• {{ ... }} voor expressies die naar de template-output worden geprint
• {# ... #} voor opmerkingen die niet in de template-output komen

Bekijk dit korte voorbeeld van een Jinja-template (met dank aan de Jinja2-documentatie):

<!DOCTYPE html>

<html lang="en">

<head>

    {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage </title>
    {% endblock %}
</head>

<body>

    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">
        {% block footer %}
        &copy; Copyright 2008 by <a href="http://domain.invalid">you </a>.
        {% endblock %}
    </div>
</body>

</html>

Je ziet hierboven dat veel van de template lijkt op een normaal HTML-document. Jinja heeft een paar extra regels nodig om de code als template te interpreteren. De {% block head %} definieert de head-sectie van het HTML-document en hoe deze template de opmaak uitbreidt. De sectie {% block title %} beschrijft waar de invoertitel wordt weergegeven. En {% endblock %} verschijnt op meerdere plaatsen omdat dat elk overeenkomstig templateblok afsluit.

Nu ben je klaar om te leren hoe je met Jinja je eigen aangepaste templates maakt!

Introductie tot Jinja

Jinja is een templatingengine waarmee je kunt bepalen hoe je documenten worden weergegeven. Specifiek voor deze tutorial richt je je op het exporteren van je Jupyter Notebook met behulp van Jinja-templates.

Importeer eerst uit Jinja2 de Template:

from jinja2 import Template

Basisrendering met templates begrijpen

Data renderen in Jinja-templates is vrij eenvoudig. Met accolades en variabelenamen kun je je data in de template tonen:

myTemplate = Template("My template is {{ something }}!")
myTemplate.render(something="awesome")

'My template is awesome!'

Door .render(input) aan te roepen, kun je de template in je Notebook weergeven, waarbij je invoer de generieke {{ something }} uit de template vervangt. Dit is een voorbeeld van expression-gebruik in Jinja.

Je kunt een template dynamischer gebruiken door een Python-statement te definiëren, dat Jinja zal interpreteren.

myFancyTemplate = Template("Let's count to 10: {% for i in range(11) %}{{i}} " "{% endfor %}")
myFancyTemplate.render()

"Let's count to 10: 0 1 2 3 4 5 6 7 8 9 10 "

Let op: je definieerde een for-lus en de template renderde de getallen van 0 tot en met 10 met spaties ertussen. De statement-syntaxis {% expression %} biedt veel flexibiliteit om een aangepaste template te maken.

Template-overerving

Om templates te maken die de standaard Jupyter-exporten uitbreiden, kun je template-overerving gebruiken. Overerving is in de programmering het concept waarbij je in een kindobject iets kunt implementeren dat gebruikmaakt van de functionaliteit die in de ouder is gedefinieerd. Een simpel voorbeeld: als je een Dog-object hebt dat kan blaffen, eten en lopen, kun je via overerving een Dalmatian-object maken dat al die eigenschappen erft en andere toevoegt, zoals heeft vlekken. In deze tutorial zie je hoe overerving erg nuttig is voor templating, omdat je meestal maar kleine aanpassingen nodig hebt om de output te personaliseren. Net als in andere overervingstalen gebruikt Jinja trefwoorden als extends en super om toegang te krijgen tot ouderdefinities.

Bekijk het voorbeeld van de oudertemplate van hierboven, genaamd base.html:

<!DOCTYPE html>
<html lang="en">

<head>
    {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage </title>
    {% endblock %}
</head>

<body>
    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">
        {% block footer %}
        &copy; Copyright 2008 by <a href="http://domain.invalid">you </a>.
        {% endblock %}
    </div>
</body>

</html>

Een kindtemplate kan er zo uitzien (met dank aan de Jinja2-documentatie):

{% extends "base.html" %}

{% block title %}Index{% endblock %}

{% block head %}
    {{ super() }}
    <style type="text/css">
        .important { color: #336699; }
    </style>
{% endblock %}

{% block content %}
    <h1>Index</h1>
    <p class="important">
      Welcome to my awesome homepage.
    </p>
{% endblock %}

Let op hoe de kindtemplate begint met {% extends "base.html" %}. Deze declaratie vertelt de Jinja-templatingengine hoe dit document moet worden behandeld (als een HTML met overerving van base.html). Met deze kindtemplate kun je specifieke eigenschappen voor de homepage opgeven (zoals een specifieke CSS-kleur). Ook zie je in het head-blok dat de kindtemplate de stijl van de ouder erft met de aanroep van super().

nbconvert gebruiken voor het exporteren van Jupyter Notebooks

Nu je de basis van de syntaxis en overerving van templates begrijpt, kun je leren hoe je je Jupyter Notebook met nbconvert exporteert en templates definieert om de output aan te passen.

Importeer eerst nbconvert:

import nbconvert

nbconvert kan output naar allerlei formaten maken. Deze tutorial focust op HTML- en LaTeX/PDF-output. Om de output in het notebook te bekijken, gebruik je de IPython-displayfunctie en --stdout in je aanroep naar nbconvert.

example = !jupyter nbconvert --to html 'Example.ipynb' --stdout
from IPython.display import HTML, display
display(HTML('\n'.join(example)))

[NbConvertApp] Converting notebook Example.ipynb to html

Dit fragment van een Notebook lijkt sterk op het oorspronkelijke .ipynb-bestand. De output wordt weergegeven als een losstaand document met koppen en tekst zoals je dat normaal in een Notebook ziet. De codecellen worden weergegeven als grijze blokken (bekend als "Notebook-stijl"). Het grootste verschil dat je ziet, is dat de standaard Jupyter-HTML-template geen "Out:"-prompts toont, zoals actieve Notebooks dat wel doen.

nbconvert en een aangepaste kindtemplate gebruiken om Jupyter Notebooks te exporteren

Meestal wil je de standaard exporttemplates van Jupyter Notebook uitbreiden en kleine ontwerpwijzigingen aanbrengen in je output.

Bekijk bijvoorbeeld deze eenvoudige template die Markdown-cellen uit de output verwijdert (genaamd rmMkdwn.tpl):

{% extends 'basic.tpl'%}

{% block markdowncell -%}
{% endblock markdowncell %}

Een template toepassen op nbconvert doe je met de optie --template=:

example = !jupyter nbconvert --to html 'Example.ipynb' --template='rmMkdwn.tpl' --stdout
display(HTML('\n'.join(example)))

[NbConvertApp] Converting notebook Example.ipynb to html Zelfs een heel eenvoudige template, zoals rmMkdwn.tpl, kan je enorm helpen om de output te personaliseren.

Bekijk deze wat complexere template, die cellen met een rode rand omlijst (genaamd boxRed.tpl):

{% extends 'full.tpl'%}

{% block any_cell %}
    <div style="border:thin solid red">
        {{ super() }}
    </div>
{% endblock any_cell %}

example = !jupyter nbconvert --to html 'Example.ipynb' --template='boxRed.tpl' --stdout
display(HTML('\n'.join(example)))

[NbConvertApp] Converting notebook Example.ipynb to html

Hierboven zie je dat de enige stijlwijziging de rode kaders rond elke cel zijn. super() wordt gebruikt om ervoor te zorgen dat elke cel zijn individuele opmaak behoudt uit de oudertemplate full.tpl.

Verschillen in templates voor export naar LaTeX en PDF

Omdat { } en % speciale tekens zijn in LaTeX, moet je (( )) en * gebruiken. Ook zijn de standaard LaTeX-templates base.tplx, article.tplx en report.tplx, die overeenkomen met LaTeX-documentklassen.

Bekijk het verwijderen van Markdown-cellen met een LaTeX-kindtemplate:

((* extends 'article.tplx' *))

((* block markdowncell -*))
((* endblock markdowncell *))

nbconvert kan LaTeX- of PDF-output maken – de PDF-output wordt gecompileerd uit de LaTeX-templates. Voor de leesbaarheid in deze tutorial, bekijk wat er gebeurt wanneer je naar PDF exporteert met rmMkdwn.tplx.

!jupyter nbconvert --to pdf 'Example.ipynb' --template='rmMkdwn.tplx'
from IPython.display import IFrame
IFrame('Example.pdf', width=800, height=500)

[NbConvertApp] Converting notebook Example.ipynb to pdf
[NbConvertApp] Support files will be in Example_files/
[NbConvertApp] Making directory Example_files
[NbConvertApp] Writing 16047 bytes to notebook.tex
[NbConvertApp] Building PDF
[NbConvertApp] Running xelatex 3 times: ['xelatex', 'notebook.tex']
[NbConvertApp] Running bibtex 1 time: ['bibtex', 'notebook']
[NbConvertApp] WARNING | bibtex had problems, most likely because there were no citations
[NbConvertApp] PDF successfully created
[NbConvertApp] Writing 16102 bytes to Example.pdf

Let op: deze output ziet er heel anders uit dan de HTML-versie. LaTeX voert de eerste Markdown-cel in als de titel van het artikel, dus die wordt nog steeds weergegeven in de output. De template verwijderde wel correct de subtitel (dus die Markdown-cel werd als echte Markdown gezien). De documentklasse article vult automatisch de datum van vandaag in – iets wat niet in het oorspronkelijke Notebook staat. Het lettertype en de witruimte verschillen van de HTML-versie. Tot slot gebruikt de output standaard de klassieke IPython-weergave, niet de "Notebook-stijl".

Als je ervoor kiest een LaTeX-documentklasse uit Jupyter uit te breiden, zorg er dan voor dat je begrijpt welke opmaak die klasse gebruikt.

Conclusie

Er zijn een paar kernpunten om te onthouden over templates, Jinja2 en nbconvert.

Templates bepalen hoe een document wordt weergegeven op een webpagina of in een ander outputformaat. Jupyter Notebooks gebruiken Jinja-templates om verschillende exportformaten weer te geven. Templates hebben overervingsregels waarmee je ouder- en kindtemplates kunt definiëren voor vergelijkbare pagina’s met iets andere opmaak.

Jinja-templates hebben statements, expressions en (optioneel) comments. Statements, gedefinieerd door {% statement %}, bepalen de structuur van de template. Expressions, gedefinieerd door {{ expression }}, vullen de template met je data. En comments, gedefinieerd door {# comment #}, worden niet in de output weergegeven – ze zijn alleen intern voor de template.

nbconvert is een Python-bibliotheek waarmee je je Jupyter Notebook kunt omzetten naar andere formaten, zoals HTML, LaTeX en PDF. nbconvert gebruikt Jinja-templates om te bepalen hoe Jupyter Notebooks in deze formaten worden weergegeven. Je kunt aangepaste templates definiëren of de standaard Jupyter-templates uitbreiden met behulp van overerving.

Nu ben je klaar om je eigen templates te maken en prachtige Jupyter Notebook-documenten te exporteren!

Referenties:

Jinja2-documentatie

Python-templatingdocumentatie

nbconvert-documentatie