nbgenerate aracı, DevSite HTML ve Markdown içerik ve şablonlarını dönüştürür
Colab uyumlu Jupyter not defterlerine aktarmanızı sağlar.
OverView
Google Colab sitesinden:
Colab not defterleri; yürütülebilir kod, zengin metin, resimler, HTML, LaTeX ve diğer öğeleri tek bir dokümanda birleştirmenizi sağlar.
Colab'de Python kodu, veya yüklemeye gerek yok. Markdown içeriği, kodla karışık şekilde kullanılabilir aynı dokümanda zengin içeriğin sunulmasına izin veren hücreler bulunur. Bu, Colab not defterlerini yalnızca nicel araştırma ve makine öğrenimi için değil, aynı zamanda API'leri ve genellikle geliştirici dokümanlarındakilere benzer kavramları göstermek ve denemek için de popüler bir çözüm haline getirir.
Bu nedenle, Colab not defterlerinde paylaşılan içerik genellikle içerikle çakışıyor Google geliştirici dokümanlarında bulabilirsiniz. nbgenerate aracı, DevSite işaretlemesini destekleyen Colab not defterleriyle manuel olarak senkronize etmeleri gerekiyor. Araç DevSite HTML ve Markdown'ı Colab tarafından kullanılan .ipynb dosya biçimine dönüştürür ve uygulamalarını öğrenin. Bu sayede DevSite içeriği, hem geliştirici dokümanları hem de Colab not defterleri için tek bir bilgi kaynağı olarak kullanılabilir.
Arka plan ve teknik ayrıntıları nbgenerate-dd adresindeki orijinal tasarım belgesinde bulabilirsiniz.
Temel kullanım
DevSite projenizdeki sayfalar için Colab not defterleri oluşturmak istiyorsanız
nbgenerate komutunu çağırmadan önce _notebooks.yaml adlı bir dosya ekleyin.
Projenize _notebooks.yaml dosyasını ekleme
Bir DevSite projesindeki sayfalardan Colab not defterleri oluşturmak için
Proje köküne (sitenizin kök diziniyle aynı dizinde) _notebooks.yaml
_project.yaml) tıklayın. Dosya, paylaşılan her sayfa için bir giriş içermelidir
Colab not defteri olarak kullanabilirsiniz. Her girişin source alanı mutlak değeri içermelidir
yolunu belirlemeniz gerekir. target alanında, oluşturulan Colab not defterlerinin yazılacağı google3 deposu yolu belirtilmelidir.
Örneğin:
- 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
Bu örnekte, oluşturulan not defterlerinin herkese açık köprülerle açılabilmesi için Copybara kullanılarak GitHub'a yansıtılan hedef yollar kullanılır. Bkz. copybara google3 yollarını GitHub ile senkronize etmeyle ilgili ayrıntılar için. Şu kaynakları da inceleyin GitHub'da oluşturulan not defterlerinin bağlantılarını ekleyen örnekler için Widget örnekleri.
Not defterleri oluşturuluyor
nbgenerate uygulamasını ilk kez çalıştırmadan önce
.bashrc ve mevcut kabuğunuza ekleyin:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Ardından, _notebooks.yaml dosyasında listelenen tüm dosyaları yeniden oluşturmak için komut satırından nbgenerate komutunu çalıştırabilirsiniz:
nbgenerate googledata/devsite/content/en/PROJECT
İşlemeyi belirtilen dosyalara veya yollara kısıtlamak için nbgenerate bağımsız değişkeni olarak bir veya daha fazla yol belirtin. Örneğin:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Dizin yolları yinelemeli olarak işlenir. _notebooks.yaml içindeki veya belirtilen dizinin altındaki tüm dosyalar işlenir.
Yukarıdaki takma adı kullanarak nbgenerate'ü çalıştırırken "İzin reddedildi" mesajını alırsanız aracı aşağıdaki komutla da çalıştırabilirsiniz:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
İçerik filtreleme
Bazı içeriklerin yalnızca DevSite sayfalarında veya oluşturulan Colab not defterinde görünmesi gerektiği durumlarda, nbgenerate dönüşüm işlemi sırasında True olarak ayarlanan is_ipynb değişkenini kullanarak içeriği filtreleyebilirsiniz. DevSite'te içerikleri seçerek yayınlarken hataları önlemek için, içeriği seçerek dahil etmesi gereken sayfaların üst kısmına şunları ekleyin:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Ardından, Colab, DevSite veya her ikisinde hangi içeriğin gösterileceğini kontrol etmek için Jinja etiketlerini kullanabilirsiniz. Örneğin:
# 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!');
```
Widget örnekleri
Siteler, genel davranışları kapsamak için sıklıkla kendi DevSite widget'larını tanımlar. Aşağıda, sitenize uyarlanabilecek is_ipynb değişkenini kullanan bazı widget örnekleri verilmiştir.
Colab not defteri düğmeleri widget'ı
Earth Engine geliştirici dokümanlarında, GitHub'daki Colab not defterleriyle senkronize edilen DevSite sayfalarında Colab'de çalıştır ve Kaynağı GitHub'da görüntüle düğmelerinin tutarlı şekilde görüntülenmesi için özel widget kullanılır.
Örnek bölüm widget'ı
Örnek bölüm widget'ı sekmeli bölümlerin nasıl ayarlanacağına ilişkin bir örnek birden fazla programlama dilinde veya ortamda sunulan kod snippet'leri için kullanılır. Widget, Colab not defterlerine yalnızca Python snippet'lerini dahil eder. Google yazarken sekmeli bölümleri görüntülemek için kullanılan işaretlemeyi de kaldırır not defterinize dokunun.