יצירת מסמכי notebook של Jupyter או Colab

הכלי nbgenerate ממיר תוכן ותבניות של DevSite ל-HTML ו-Markdown ל-notebooks של Jupyter שתואמים ל-Colab.

OverView

מהאתר של Google Colab:

קובצי notebook של Colab מאפשרים לשלב קוד להרצה וטקסט עשיר במסמך אחד, יחד עם תמונות, HTML, LaTeX ועוד.

ב-Colab, אפשר לכתוב קוד Python ולהריץ אותו מדפדפן אינטרנט או התקנה נוספת. אפשר לשלב בין תוכן Markdown לבין קוד כדי לאפשר הזנה של תוכן עשיר באותו מסמך. לכן, מחברות ב-Colab הן פתרון פופולרי לא רק למחקר כמותי וללמידת מכונה, אלא גם להדגמה ולניסוי של ממשקי API ומושגים כמו אלה שמופיעים בדרך כלל במסמכי עזרה למפתחים.

לכן, תוכן ששותף ב-notebooks של Colab חופף לעיתים קרובות לתוכן שפורסם בתיעוד למפתחים של Google. בעזרת הכלי nbgenerate, אין צורך לסנכרן באופן ידני את ה-markup של DevSite עם קובצי notebook תומכים ב-Colab. הכלי ממירה את ה-HTML של DevSite ואת ה-Markdown לפורמט קובץ .ipynb שמשמש את Colab יישומים אחרים של notebook של Jupyter. כך אפשר להשתמש בתוכן של DevSite כמקור מידע מהימן אחד גם למסמכי notebook של המפתחים וגם ל-notebooks של Colab.

ניתן למצוא רקע ופרטים טכניים במסמך העיצוב המקורי בכתובת nbgenerate-dd.

שימוש בסיסי

כדי ליצור קובצי notebook של Colab לדפים בפרויקט DevSite, צריך: צריך להוסיף קובץ בשם _notebooks.yaml לפני שמפעילים את הפקודה nbgenerate.

הוספת _notebooks.yaml לפרויקט

כדי ליצור מחברות של Colab מדפים בפרויקט DevSite, מוסיפים קובץ בשם _notebooks.yaml לספריית הבסיס של הפרויקט (באותה ספרייה שבה נמצא הקובץ _project.yaml של האתר). הקובץ צריך לכלול רשומה אחת לכל דף שרוצים לשתף כמחברות של Colab. השדה source בכל רשומה חייב להכיל את הנתיב המוחלט בתוך דייר DevSite כדי שיהיה אפשר להמיר אותו למחברת ב-Colab. בשדה target צריך לציין את נתיב המאגר של google3 שבו ייכתבו קובצי ה-notebook של Colab שנוצרו.

לדוגמה:

- 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

בדוגמה הזו נעשה שימוש בנתיבי יעד שמשוחזרים ל-GitHub באמצעות Copybara, כדי שאפשר יהיה לפתוח את המחברות שנוצרו באמצעות היפר-קישורים שגלויים לכולם. ראו copybara לקבלת פרטים על סנכרון נתיבי Google3 עם GitHub. כדאי לעיין גם בדוגמאות לווידג'טים כדי לראות דוגמאות להוספת קישורים למסמכי notebook שנוצרו ב-GitHub.

יצירת מחברות

לפני הרצת nbgenerate בפעם הראשונה, עליך להגדיר כינוי ב .bashrc ולמעטפת הנוכחית:

alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"

לאחר מכן אפשר להריץ את nbgenerate משורת הפקודה כדי ליצור מחדש את כל הקבצים רשום ב-_notebooks.yaml:

nbgenerate googledata/devsite/content/en/PROJECT

צריך לציין נתיב אחד או יותר כארגומנטים ל-nbgenerate כדי להגביל את העיבוד ל- את הקבצים או הנתיבים שצוינו, לדוגמה:

nbgenerate third_party/devsite/developers/en/earth-engine/guides

נתיבי הספריות עוברים עיבוד באופן רפלוקטיבי. כל הקבצים ב-_notebooks.yaml שבספרייה שצוינה או מתחתיה יעברו עיבוד.

אם מופיעה הודעת השגיאה 'Permission denied' כשמריצים את nbgenerate באמצעות החלופה שלמעלה, אפשר גם להריץ את הכלי באמצעות הפקודה הבאה:

blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT

סינון תוכן

במקרים שבהם חלק מהתוכן צריך להופיע רק בדפי DevSite או ב- notebook של Colab, אבל לא של שניהם, אפשר לסנן תוכן באמצעות משתנה is_ipynb, שמוגדר ל-True במהלך ההמרה מסוג nbgenerate תהליך האימות. כדי למנוע שגיאות ב-Staging ובפרסום ב-DevSite, צריך להוסיף את הקוד בסמוך לחלק העליון של דפים שצריכים לכלול תוכן באופן סלקטיבי:

    
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
     

לאחר מכן אפשר להשתמש בתגי Jinja כדי לקבוע איזה תוכן יופיע ב-Colab, ב-DevSite, או לשניהם. לדוגמה:

# 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!');
```

דוגמאות לווידג'טים

לעיתים קרובות אתרים מגדירים ווידג'טים של DevSite משלהם כדי להכיל התנהגויות נפוצות. בהמשך מפורטות כמה דוגמאות לווידג'טים שמשתמשים במשתנה is_ipynb, שניתן להתאים לאתר שלכם.

ווידג'ט הלחצנים של Colab

במסמכי התיעוד למפתחים של Earth Engine נעשה שימוש בווידג'ט בהתאמה אישית כדי להציג באופן עקבי את הלחצנים הרצה ב-Colab והצגת המקור ב-GitHub בדפי DevSite שמסונכרנים עם קובצי notebook של Colab ב-GitHub.

ווידג'ט של קטע לדוגמה

ווידג'ט הקטע לדוגמה שממחישה איך להגדיר קטעים בכרטיסיות לקטעי קוד שמוצגים במספר שפות או סביבות תכנות. הווידג'ט מטפל רק בהוספה של קטעי קוד Python בקובצי notebook של Colab. הוא גם מסיר את התגים ששימשו להצגת הקטעים עם הכרטיסיות בזמן כתיבת המחברות.