Templat Kustom untuk Jupyter Notebook dengan Jinja2

Dalam data science, Anda sering kali perlu membuat laporan pekerjaan untuk ditunjukkan kepada pengambil keputusan atau personel non-teknis lainnya. Mengonversi Jupyter Notebook Anda menjadi dokumen PDF atau HTML yang stabil lebih mudah dibagikan kepada rekan yang tidak memiliki Python atau Jupyter terpasang. Python menggunakan pustaka bernama nbconvert dan bahasa templating bernama Jinja2 untuk mengonversi dokumen. Templat menentukan bagaimana sebuah dokumen akan ditampilkan di laman web atau format keluaran lainnya. Memahami cara menyesuaikan templat bermanfaat untuk membuat laporan Notebook yang lebih rapi.

Jupyter Notebook adalah cara untuk menjalankan kode Python di browser Anda. Jika Anda ingin mempelajari lebih lanjut tentang Python, pastikan untuk melihat kursus gratis kami Intro to Python for Data Science.

Dalam tutorial ini, Anda akan membahas topik-topik berikut:

• Templat dan perancang templat Jinja2.
• Rendering templat dan pewarisan.
• Cara menggunakan nbconvert untuk mengekspor Notebook Anda.
• Sintaks dan struktur untuk memperluas templat default Jupyter untuk ekspor HTML.
• Perbedaan saat mengekspor ke format LaTeX dan PDF.

Apa itu Templat?

Dari wiki Python: "Templating, khususnya web templating, adalah cara untuk merepresentasikan data dalam berbagai bentuk... Sering kali, solusi templating melibatkan sebuah dokumen (templat) dan data. Templat biasanya terlihat mirip dengan keluaran akhir, dengan placeholder alih-alih data aktual"

Jupyter Notebook dapat diekspor dengan mudah menggunakan File -> Download As (Di Jupyter Lab, Anda akan melihat Export Notebook As). Opsi ini menggunakan templat default yang disimpan di lingkungan utama Jupyter. Jinja2 adalah bahasa templating yang kuat untuk Python guna mendefinisikan blok dan tata letak. Templat memiliki bagian-bagian, yang didefinisikan oleh tag, yang memberi tahu templat cara merender data masukan. Data menggantikan variabel atau ekspresi ketika templat dirender.

Pembatas untuk berbagai bagian dalam templat adalah:

• {% ... %} untuk Pernyataan (Statements)
• {{ ... }} untuk Ekspresi yang dicetak ke keluaran templat
• {# ... #} untuk Komentar yang tidak disertakan dalam keluaran templat

Lihat contoh singkat templat Jinja berikut (dikutip dari dokumentasi Jinja2):

<!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>

Anda dapat melihat di atas bahwa sebagian besar templat menyerupai dokumen HTML biasa. Jinja memerlukan beberapa baris tambahan untuk menafsirkan kode sebagai templat. {% block head %} mendefinisikan bagian head dari dokumen HTML dan bagaimana templat ini akan memperluas pemformatannya. Bagian {% block title %} menjelaskan di mana judul masukan akan ditampilkan. Dan {% endblock %} muncul di beberapa tempat karena itu menutup blok templat yang bersesuaian.

Sekarang Anda siap mempelajari cara menggunakan Jinja untuk membuat templat kustom Anda sendiri!

Pengantar Jinja

Jinja adalah mesin templating yang memungkinkan Anda menentukan bagaimana dokumen Anda akan ditampilkan. Secara khusus, untuk tutorial ini, Anda akan berfokus pada cara mengekspor Jupyter Notebook Anda dengan bantuan templat Jinja.

Pertama, dari Jinja2 impor Template:

from jinja2 import Template

Memahami Rendering Dasar dengan Templat

Merender data dalam templat Jinja cukup mudah. Dengan menggunakan kurung kurawal dan nama variabel, Anda dapat menampilkan data Anda dalam templat:

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

'My template is awesome!'

Memanggil .render(input) memungkinkan Anda menampilkan templat di Notebook Anda dengan masukan Anda menggantikan {{ something }} generik dari templat. Ini adalah contoh penggunaan expression dalam Jinja.

Anda dapat menggunakan templat secara lebih dinamis dengan mendefinisikan statement Python, yang akan ditafsirkan oleh Jinja.

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 "

Perhatikan Anda mendefinisikan loop for dan templat merender angka dari 0 hingga 10 dengan spasi di antaranya. Sintaks statement {% expression %} memberikan banyak fleksibilitas untuk membuat templat kustom.

Pewarisan Templat

Untuk membuat templat yang memperluas ekspor default Jupyter, Anda dapat menggunakan pewarisan templat. Pewarisan adalah konsep dalam pemrograman bahwa Anda dapat mengimplementasikan sesuatu dalam objek anak yang dapat memanfaatkan fungsionalitas yang didefinisikan induknya. Contoh sederhana adalah jika Anda memiliki objek Dog yang dapat bark, eat, dan walk, Anda dapat menggunakan pewarisan untuk membuat objek Dalmatian yang dapat mewarisi semua atribut tersebut dan menambahkan yang lain, seperti has spots. Anda akan melihat dalam tutorial ini bagaimana pewarisan sangat berguna untuk templating, karena biasanya hanya perubahan kecil yang diperlukan untuk menyesuaikan keluaran. Seperti bahasa pewarisan lainnya, Jinja menggunakan kata kunci seperti extends dan super untuk mengakses definisi induk.

Lihat contoh templat induk dari atas, bernama 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>

Templat anak mungkin terlihat seperti ini (dikutip dari dokumentasi Jinja2):

{% 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 %}

Perhatikan bagaimana templat anak dimulai dengan {% extends "base.html" %}. Pernyataan ini memberi tahu mesin templating Jinja cara memperlakukan dokumen ini (sebagai HTML dengan pewarisan dari base.html). Menggunakan templat anak ini memungkinkan penentuan atribut berbeda untuk beranda (seperti warna CSS tertentu). Selain itu, Anda dapat melihat di blok head bahwa templat anak mewarisi gaya induk dengan pemanggilan super().

Menggunakan nbconvert untuk Mengekspor Jupyter Notebook

Sekarang setelah Anda memahami sintaks dasar dan pewarisan templat, Anda dapat mempelajari cara mengekspor Jupyter Notebook dengan nbconvert dan mendefinisikan templat untuk menyesuaikan keluaran.

Pertama impor nbconvert:

import nbconvert

nbconvert dapat membuat keluaran ke berbagai format. Tutorial ini akan berfokus pada keluaran HTML dan LaTeX/PDF. Untuk melihat keluaran di notebook, gunakan fungsi tampilan IPython dan --stdout dalam pemanggilan Anda ke nbconvert.

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

[NbConvertApp] Mengonversi notebook Example.ipynb ke html

Cuplikan Notebook ini terlihat sangat mirip dengan berkas .ipynb aslinya. Keluaran ditampilkan sebagai dokumen mandiri dengan judul dan teks sebagaimana biasanya ditampilkan di Notebook. Blok sel kode ditampilkan sebagai kotak abu-abu (dikenal sebagai "gaya Notebook"). Perbedaan utama yang dapat Anda lihat adalah templat HTML default Jupyter tidak menampilkan prompt "Out:", seperti Notebook aktif.

Menggunakan nbconvert dan Templat Anak Kustom untuk Mengekspor Jupyter Notebook

Biasanya, Anda akan ingin memperluas templat ekspor default Jupyter Notebook dan membuat perubahan desain kecil pada keluaran Anda.

Misalnya, lihat templat sederhana ini yang menghapus sel Markdown dari keluaran (disebut rmMkdwn.tpl):

{% extends 'basic.tpl'%}

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

Menerapkan templat ke nbconvert dilakukan dengan opsi --template=:

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

[NbConvertApp] Mengonversi notebook Example.ipynb ke html Bahkan templat yang sangat sederhana, seperti rmMkdwn.tpl, dapat sangat membantu Anda menyesuaikan keluaran.

Lihat templat yang lebih rumit ini, yang memberi bingkai merah pada sel (disebut 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] Mengonversi notebook Example.ipynb ke html

Di atas, Anda dapat melihat bahwa satu-satunya perubahan gaya adalah kotak merah di sekitar setiap sel. super() digunakan untuk memastikan bahwa setiap sel mempertahankan gaya individualnya dari templat induk full.tpl.

Perbedaan Templat untuk Mengekspor ke LaTeX dan PDF

Karena { } dan % adalah karakter khusus dalam LaTeX, Anda harus menggunakan (( )) dan *. Selain itu templat LaTeX default adalah base.tplx, article.tplx, dan report.tplx, yang sesuai dengan kelas dokumen LaTeX.

Lihat cara menghapus sel Markdown dengan templat anak LaTeX:

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

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

nbconvert dapat membuat keluaran LaTeX atau PDF — keluaran PDF dikompilasi dari templat LaTeX. Untuk memudahkan penayangan dalam tutorial ini, lihat apa yang terjadi saat Anda mengekspor ke PDF menggunakan 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

Perhatikan, keluaran ini hasilnya sangat berbeda dari versi HTML. LaTeX memasukkan sel Markdown pertama ke dalam judul artikel, sehingga tetap ditampilkan pada keluaran. Templat memang benar menghapus subjudul (jadi ia menganggap sel Markdown tersebut sebagai Markdown sejati). Kelas dokumen artikel memperbarui tanggal ke hari ini — yang bukan bagian dari Notebook asli. Jenis huruf dan spasi berbeda dari versi HTML. Terakhir, secara default keluaran menggunakan tampilan IPython klasik, bukan tampilan "gaya Notebook".

Jika Anda memilih untuk memperluas kelas dokumen LaTeX yang ada di Jupyter, pastikan Anda memahami pemformatan apa yang akan digunakan.

Kesimpulan

Ada beberapa hal kunci yang perlu diingat tentang templat, Jinja2, dan nbconvert.

Templat menentukan bagaimana sebuah dokumen akan ditampilkan di laman web atau format keluaran lain. Jupyter Notebook mengimplementasikan templat Jinja untuk menampilkan berbagai format ekspor. Templat memiliki aturan pewarisan yang memungkinkan Anda mendefinisikan templat induk dan anak untuk halaman serupa, dengan pemformatan yang sedikit berbeda.

Templat Jinja memiliki statements, expressions, dan (opsional) comments. Statements, yang didefinisikan oleh {% statement %}, mendefinisikan struktur templat. Expressions, yang didefinisikan oleh {{ expression }}, mengisi templat dengan data Anda. Dan comments, yang didefinisikan oleh {# comment #}, tidak ditampilkan pada keluaran — hanya untuk internal templat.

nbconvert adalah pustaka Python yang memungkinkan Anda mengonversi Jupyter Notebook ke format lain, seperti HTML, LaTeX, dan PDF. nbconvert menggunakan templat Jinja untuk menentukan bagaimana Jupyter Notebook akan ditampilkan dalam format-format ini. Anda dapat mendefinisikan templat kustom atau memperluas templat default Jupyter menggunakan pewarisan.

Sekarang Anda siap mulai membuat templat sendiri dan mengekspor dokumen Jupyter Notebook yang indah!

Referensi:

Dokumentasi Jinja2

Dokumentasi templating Python

Dokumentasi nbconvert