Инструмент nbgenerate преобразует контент и шаблоны DevSite HTML и Markdown в блокноты Jupyter, совместимые с Colab.
Обзор
С сайта 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, куда будут записываться созданные блокноты 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 , для которой в процессе преобразования 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 используется специальный виджет для последовательного отображения кнопок «Запустить в Colab» и «Просмотреть исходный код» на кнопках GitHub на страницах DevSite, синхронизированных с записными книжками Colab в GitHub.
Пример виджета раздела
Виджет «Пример раздела» представляет собой пример настройки разделов с вкладками для фрагментов кода, представленных на нескольких языках программирования или в различных средах. Виджет заботится о включении только фрагментов Python в блокноты Colab. Он также удаляет разметку, используемую для отображения разделов с вкладками при написании записной книжки.