Alat nbgenerate mengonversi konten dan template HTML DevSite dan Markdown
ke dalam notebook Jupyter yang kompatibel dengan Colab.
OverView
Dari situs Google Colab:
Notebook Colab memungkinkan Anda menggabungkan kode yang dapat dieksekusi dan rich text dalam satu dokumen, bersama dengan gambar,HTML, LaTeX dan lainnya.
Di Colab, kode Python dapat ditulis dan dieksekusi dari browser web tanpa penyiapan atau penginstalan tambahan. Konten Markdown dapat diselingi dengan sel kode agar konten yang kaya dapat disediakan dalam dokumen yang sama. Hal ini membuat Notebook Colab adalah solusi populer tidak hanya untuk riset kuantitatif dan machine learning, tetapi juga untuk menunjukkan dan bereksperimen dengan API konsep seperti yang biasa ditemukan dalam dokumentasi pengembang.
Karena alasan ini, konten yang dibagikan di notebook Colab sering kali tumpang-tindih dengan konten yang dipublikasikan dalam dokumentasi developer Google. Alat {i>nbgenerate<i} menghilangkan perlu menyinkronkan markup DevSite secara manual dengan notebook Colab yang mendukung. Alat ini mengonversi HTML dan Markdown DevSite ke format file .ipynb yang digunakan oleh Colab dan implementasi notebook Jupyter lainnya. Hal ini memungkinkan konten DevSite digunakan sebagai satu sumber tepercaya untuk dokumen developer dan notebook Colab.
Latar belakang dan detail teknis dapat ditemukan dalam dokumen desain asli di nbgenerate-dd.
Penggunaan dasar
Agar dapat membuat notebook Colab untuk halaman di project DevSite, Anda harus
tambahkan file bernama _notebooks.yaml sebelum memanggil perintah nbgenerate.
Menambahkan _notebooks.yaml ke project Anda
Untuk membuat notebook Colab dari halaman dalam project DevSite, tambahkan file bernama _notebooks.yaml ke root project (di direktori yang sama dengan _project.yaml situs Anda). File harus menyertakan satu entri untuk setiap halaman yang dibagikan sebagai notebook Colab. Kolom source dari setiap entri harus berisi jalur absolut dalam tenant DevSite Anda untuk dikonversi menjadi notebook Colab. Tujuan
Kolom target harus menentukan jalur depot google3 tempat Colab dibuat
{i>notebook<i} akan ditulis.
Contoh:
- source: /earth-engine/ee-image.html
target: //depot/google3/third_party/earthengine_community/ipynb/ee-image.ipynb
- source: /earth-engine/guides/image_objects.md
target: //depot/google3/third_party/earthengine_community/ipynb/guides/image_objects.ipynb
Contoh ini menggunakan jalur target yang dicerminkan ke GitHub menggunakan Copybara sehingga bahwa {i>notebook<i} yang dihasilkan dapat dibuka melalui {i>hyperlink<i} yang dapat diakses oleh publik. Lihat copybara untuk mengetahui detail tentang cara menyinkronkan jalur google3 ke GitHub. Lihat juga Contoh widget untuk contoh yang menambahkan link ke notebook yang dibuat di GitHub.
Membuat notebook
Sebelum menjalankan nbgenerate untuk pertama kalinya, tentukan alias di
.bashrc dan ke shell saat ini:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Kemudian, Anda dapat menjalankan nbgenerate dari command line untuk membuat ulang semua file
yang tercantum dalam _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Tentukan satu atau beberapa jalur sebagai argumen ke nbgenerate yang ingin dibatasi pemrosesannya
file atau jalur yang ditentukan, misalnya:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Jalur direktori diproses secara rekursif; setiap file di _notebooks.yaml di atau
di bawah direktori yang ditentukan akan diproses.
Jika Anda menerima pesan "Izin ditolak" saat menjalankan nbgenerate menggunakan alias di atas, Anda juga dapat menjalankan alat ini dengan perintah berikut:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Memfilter konten
Dalam kasus saat beberapa konten seharusnya hanya muncul di halaman DevSite atau di
yang dibuat notebook Colab, tetapi tidak keduanya, Anda dapat memfilter konten menggunakan
Variabel is_ipynb, yang ditetapkan ke True selama konversi nbgenerate
{i>checkout<i}. Untuk mencegah error saat melakukan staging dan memublikasikan ke DevSite, tambahkan kode berikut di dekat bagian atas halaman yang perlu menyertakan konten secara selektif:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Kemudian, Anda dapat menggunakan tag Jinja untuk mengontrol konten mana yang muncul di Colab, DevSite, atau keduanya. Contoh:
# Overview
This section will show in both the DevSite page and in the Colab notebook as
a text cell.
{% if is_ipynb %}
This content will only appear in Colab notebooks but not on DevSite pages. This
is useful for providing Colab-specific initialization and setup instructions or
code.
{% endif %}
{% if not is_ipynb %}
```js
// This code snippet will only be rendered in DevSite but not in Colab
// notebooks.
console.log('Hello, nbgenerate!');
```
{% endif %}
```py
# This snippet will appear in both DevSite and in the Colab notebook as a code
# cell.
print('Hello, nbgenerate!');
```
Contoh widget
Situs sering kali menentukan widget DevSite-nya sendiri untuk mengenkapsulasi perilaku umum. Berikut beberapa contoh widget yang menggunakan variabel is_ipynb, yang dapat disesuaikan dengan situs Anda.
Widget tombol notebook Colab
Dokumentasi developer Earth Engine menggunakan widget kustom untuk menampilkan tombol Run in Colab dan View source on GitHub secara konsisten di halaman DevSite yang disinkronkan ke notebook Colab di GitHub.
Contoh widget bagian
Widget bagian contoh memberikan contoh cara menyiapkan bagian tab untuk cuplikan kode yang disajikan dalam berbagai bahasa pemrograman atau lingkungan. Widget ini hanya menyertakan cuplikan Python di notebook Colab. Ini juga menghapus markup yang digunakan untuk menampilkan bagian bertab saat menulis {i>notebook<i} tersebut.