این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تولید نوت بوک Jupyter/Colab

ابزار nbgenerate محتوا و قالب‌های DevSite HTML و Markdown را به نوت‌بوک‌های Jupyter سازگار با Colab تبدیل می‌کند.

نمای کلی

نوت بوک های Colab به شما این امکان را می دهند که کد اجرایی و متن غنی را در یک سند واحد به همراه تصاویر، HTML، LaTeX و موارد دیگر ترکیب کنید.

در Colab، کد پایتون را می توان از یک مرورگر وب بدون هیچ راه اندازی یا نصب اضافی نوشته و اجرا کرد. محتوای Markdown را می توان با سلول های کد در هم آمیخت تا امکان ارائه محتوای غنی در همان سند فراهم شود. این باعث می‌شود نوت‌بوک‌های Colab نه تنها برای تحقیقات کمی و یادگیری ماشین، بلکه برای نشان دادن و آزمایش با APIها و مفاهیمی مانند آنچه که معمولاً در اسناد توسعه‌دهنده یافت می‌شود، راه‌حلی محبوب باشد.

به همین دلیل، محتوای به اشتراک گذاشته شده در نوت بوک های Colab اغلب با محتوای منتشر شده در اسناد توسعه دهنده Google همپوشانی دارد. ابزار nbgenerate نیاز به همگام سازی دستی نشانه گذاری DevSite با نوت بوک های Colab را برطرف می کند. این ابزار DevSite HTML و Markdown را به فرمت فایل ipynb. مورد استفاده توسط Colab و سایر اجراهای نوت بوک Jupyter تبدیل می کند. این به محتوای DevSite اجازه می دهد تا به عنوان یک منبع حقیقت واحد برای اسناد توسعه دهنده و نوت بوک های Colab استفاده شود.

پس زمینه و جزئیات فنی را می توان در سند طراحی اصلی در nbgenerate-dd یافت.

استفاده اساسی

برای تولید نوت بوک های Colab برای صفحات پروژه DevSite خود، باید قبل از فراخوانی دستور nbgenerate فایلی به نام _notebooks.yaml اضافه کنید.

افزودن _notebooks.yaml به پروژه شما

برای تولید نوت بوک های Colab از صفحات یک پروژه DevSite، فایلی به نام _notebooks.yaml را به ریشه پروژه اضافه کنید (در همان دایرکتوری سایت _project.yaml ). این فایل باید شامل یک ورودی برای هر صفحه ای باشد که به عنوان دفترچه یادداشت Colab به اشتراک گذاشته می شود. فیلد 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

این مثال از مسیرهای هدفی استفاده می‌کند که با استفاده از Copybara به GitHub منعکس شده‌اند تا نوت‌بوک‌های تولید شده را بتوان از طریق لینک‌های در دسترس عموم باز کرد. برای جزئیات در مورد نحوه همگام سازی مسیرهای google3 با GitHub به copybara مراجعه کنید. همچنین به مثال‌های ویجت برای مثال‌هایی که پیوندهایی به نوت‌بوک‌های تولید شده در 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 با استفاده از نام مستعار بالا، "Permission denied" را دریافت کردید، می توانید ابزار را با دستور زیر نیز اجرا کنید:

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

فیلتر کردن محتوا

در مواردی که برخی از محتواها فقط باید در صفحات DevSite یا در نوت بوک تولید شده Colab ظاهر شوند، اما نه هر دو، می توانید محتوا را با استفاده از متغیر is_ipynb که در طول فرآیند تبدیل nbgenerate روی True تنظیم شده است، فیلتر کنید. برای جلوگیری از بروز خطا در هنگام استقرار و انتشار در 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 از یک ویجت سفارشی برای نمایش مداوم Run in Colab و View source روی دکمه‌های GitHub در صفحات DevSite که با نوت‌بوک‌های Colab در GitHub همگام‌سازی شده‌اند، استفاده می‌کند.

ویجت بخش نمونه

ویجت بخش نمونه مثالی از نحوه تنظیم بخش های تب دار برای قطعه کد ارائه شده در چندین زبان برنامه نویسی یا محیط ارائه می دهد. ویجت فقط از گنجاندن قطعه های پایتون در نوت بوک های Colab مراقبت می کند. همچنین نشانه‌گذاری مورد استفاده برای نمایش بخش‌های برگه‌دار هنگام نوشتن نوت‌بوک را حذف می‌کند.