Генериране на преносими компютри Jupyter/Colab

Инструментът nbgenerate преобразува съдържание и шаблони на DevSite HTML и Markdown в съвместими с Colab преносими компютри Jupyter.

Преглед

От сайта на Google Colab :

Бележниците на Colab ви позволяват да комбинирате изпълним код и обогатен текст в един документ, заедно с изображения, HTML, LaTeX и др.

В Colab кодът на Python може да бъде написан и изпълнен от уеб браузър без допълнителна настройка или инсталация. Съдържанието на Markdown може да бъде разпръснато с кодови клетки, за да позволи предоставянето на богато съдържание в същия документ. Това прави преносимите компютри Colab популярно решение не само за количествени изследвания и машинно обучение, но и за демонстриране и експериментиране с API и концепции като тези, които обикновено се срещат в документацията за разработчици.

Поради тази причина съдържанието, споделено в бележниците на Colab, често се припокрива със съдържание, публикувано в документацията за разработчици на Google. Инструментът nbgenerate елиминира необходимостта от ръчно синхронизиране на маркирането на DevSite с поддържащите преносими компютри Colab. Инструментът преобразува DevSite HTML и Markdown във файловия формат .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. Вижте също примери за Widget за примери, които добавят връзки към генерирани бележници в 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 използва персонализирана джаджа за последователно показване на бутоните Run in Colab и View source на GitHub на страниците на DevSite, синхронизирани с бележници Colab в GitHub.

Примерна джаджа за раздел

Приспособлението за примерна секция предоставя пример за това как да настроите секции с раздели за кодови фрагменти, представени в множество програмни езици или среди. Приспособлението се грижи само за включването на Python фрагменти в бележниците на Colab. Той също така премахва маркирането, използвано за показване на разделите с раздели при писане на бележника.