Створення блокнотів Jupyter/Colab

Інструмент nbgenerate перетворює вміст і шаблони DevSite HTML і Markdown у блокноти Jupyter, сумісні з Colab.

Огляд

З сайту Google Colab :

Блокноти Colab дозволяють поєднувати виконуваний код і форматований текст в одному документі разом із зображеннями, HTML, LaTeX тощо.

У Colab код Python можна писати та виконувати з веб-переглядача без додаткового налаштування чи встановлення. Вміст розмітки можна перемежовувати комірками коду, щоб забезпечити розширений вміст у тому самому документі. Це робить блокноти Colab популярним рішенням не лише для кількісних досліджень і машинного навчання, але й для демонстрації та експериментування з API та концепціями, подібними до тих, які зазвичай містяться в документації розробників.

З цієї причини вміст, опублікований у блокнотах 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. Поле source кожного запису має містити абсолютний шлях у вашому клієнті DevSite, який потрібно перетворити на блокнот Colab. target поле має вказати шлях google3 depot, куди будуть записані згенеровані блокноти 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. Він також видаляє розмітку, яка використовується для відображення розділів із вкладками під час написання блокнота.