تحوّل أداة "nbgenerate" المحتوى والنماذج في DevSite HTML و Markdown
إلى أوراق ملاحظات Jupyter المتوافقة مع Colab.
OverView
من موقع Google Colab الإلكتروني:
تتيح لك أوراق ملاحظات Colab دمج الرموز البرمجية التنفيذية والنصوص المنسّقة في مستند واحد، بالإضافة إلى الصور وHTML وLaTeX والمزيد.
في Colab، يمكن كتابة رمز Python وتنفيذه من متصفّح ويب بدون أي إعداد أو تثبيت إضافي. يمكن إدراج محتوى Markdown بين خلايا برمجية للسماح بتقديم محتوى غني في المستند نفسه. وهذا يجعل ملفات "دفتر ملاحظات Colab" حلًا شائعًا ليس فقط للبحث الكمي وتكنولوجيا تعلُّم الآلة، بل أيضًا لعرض واجهات برمجة التطبيقات ومحاولة استخدامها ومحاولة استخدام المفاهيم، مثل تلك التي تظهر عادةً في مستندات المطوّرين.
لهذا السبب، غالبًا ما يتداخل المحتوى الذي تتم مشاركته في أوراق ملاحظات Colab مع المحتوى المنشور في مستندات مطوّري Google. تُلغي أداة nbgenerate الحاجة إلى مزامنة ترميز DevSite يدويًا مع أوراق ملاحظات Colab المتوافقة. تعمل الأداة على تحويل تنسيق HTML وMarkdown في DevSite إلى تنسيق ملف .ipynb الذي تستخدمه Colab و عمليات تنفيذ أوراق ملاحظات Jupyter الأخرى. يتيح هذا الإجراء استخدام محتوى DevSite. كمصدر وحيد للمعلومات لكل من مستندات المطوّرين وأوراق ملاحظات Colab.
يمكن العثور على الخلفية والتفاصيل الفنية في مستند التصميم الأصلي على nbgenerate-dd.
الاستخدام الأساسي
لإنشاء أوراق ملاحظات Colab للصفحات في مشروع DevSite، عليك إجراء ما يلي:
أضِف ملفًا باسم _notebooks.yaml قبل استدعاء الأمر nbgenerate.
إضافة ملف _notebooks.yaml إلى مشروعك
لإنشاء أوراق ملاحظات Colab من صفحات في مشروع DevSite، عليك إضافة ملف باسم
_notebooks.yaml إلى جذر المشروع (في الدليل نفسه الذي يتضمّن موقعك الإلكتروني)
_project.yaml). يجب أن يتضمن الملف إدخالاً واحدًا لكل صفحة تتم مشاركتها
كملف Colab notebook. يجب أن يحتوي الحقل source لكل إدخال على القيمة المطلقة
المسار داخل مستأجر DevSite لتحويله إلى ورقة ملاحظات Colab. تشير رسالة الأشكال البيانية
يجب أن يحدّد الحقل target مسار مستودع google3 الذي تم إنشاء 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. يمكن أيضًا مراجعة أمثلة على الأدوات لعرض أمثلة على إضافة روابط إلى أوراق الملاحظات التي تم إنشاؤها في 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 في الدليل المحدّد أو
أسفله.
إذا ظهرت لك رسالة "تم رفض الإذن" عند تشغيل nbgenerate باستخدام الاسم المعرِّف
أعلاه، يمكنك أيضًا تشغيل الأداة باستخدام الأمر التالي:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
فلترة المحتوى
في الحالات التي يجب أن يظهر فيها بعض المحتوى إما في صفحات DevSite فقط أو في
تم إنشاء ورقة ملاحظات Colab ولكن ليس كليهما، فيمكنك فلترة المحتوى باستخدام
المتغيّر "is_ipynb"، والذي يتم ضبطه على True أثناء الإحالة الناجحة "nbgenerate"
الدفع. لتجنُّب حدوث أخطاء عند النشر إلى 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 التي تمت مزامنتها مع أوراق ملاحظات Colab في GitHub.
نموذج أداة القسم
أداة نموذج القسم تقدّم مثالاً على كيفية إعداد أقسام مُقسّمة بعلامات تبويب لمقتطفات الرموز البرمجية المقدَّمة بلغات برمجة أو بيئات متعددة. تهتم الأداة المصغّرة بتضمين مقتطفات Python فقط في دفاتر ملاحظات Colab. ويؤدي ذلك أيضًا إلى إزالة الترميز المستخدَم لعرض الأقسام التي تتضمّن علامات تبويب عند كتابة ملف الملاحظات.