Ранее мы анонсировали JupyterLite — дистрибутив JupyterLab, полностью запускаемый в браузере. Материалом, который будет полезен авторам документации библиотек Python, делимся к старту флагманского курса по Data Science.

JupyterLite по умолчанию поставляется с ядром на Pyodide и IPython и самым разным функционалом, от автодополнения кода до интерактивных визуализаций. В последних релизах JupyterLite по умолчанию поставляется c REPL, которая устанавливается на любой сайт.

Встраиваем на сайт интерактивную консоль Python

Допустим, у вас есть работающий статический веб-сайт. Например, блог на Jekyll. Интерактивная консоль REPL встраивается в него простым фрагментом кода:

<iframe
  src="https://jupyterlite.github.io/demo/repl/index.html?kernel=python&toolbar=1"
  width="100%"
  height="500px"
>
</iframe>

Вот и всё: интерактивная REPL Python встроена!

Выше вы видите развёрнутый на GitHub Pages демонстрационный сайт. Чтобы полностью контролировать его, использовать собственную конфигурацию и расширения, мы рекомендуем настроить развёртывание сайта JupyterLite, о котором расскажем позже.

Заряжаем документацию NumPy

Интерактивная консоль уже используется проектом NumPy на сайте документации numpy.org. Предшествующая консоль работала на Thebe и mybinder.org, что давало большую гибкость и возможность попробовать NumPy без установок на компьютер. 

Перед вводом кода каждому пользователю приходилось запускать новый сервер Jupyter в модуле биндинга к Binder и ждать запуска ядра. Какое-то время этот подход работал, но его сопровождение затруднились.

Теперь пользователи в numpy.org могут задействовать интерактивную консоль и пробовать NumPy в браузерах с помощью Python REPL на JupyterLite. Это сильно сокращает необходимость в ресурсах и даёт быстрое, плавное взаимодействие с пользователем:

Сегодня в основе REPL лежит знакомая пользователям Jupyter по внешнему виду JupyterLab Code Console. В качестве следующей версии REPL рассматриваются и другие интерфейсы, например Single Executable Cell.

Try Jupyter

К освоению инструментария JupyterLite недавно приступили и на официальном сайте Jupyter. На сайте try.jupyter.org используется общедоступная технология развёртывания mybinder.org. Она позволяет пробовать различные подпроекты Jupyter, например Voilà и ядра на основе Xeus.

Эта конфигурация хорошо работает уже много лет, но недавно в проекте Binder возникли проблемы с финансированием, из-за чего общая ёмкость Binder резко сократилась. А значит, пользователям для проектов доступно меньше ресурсов. Это повлияло и на сайт Try Jupyter.

Чтобы смягчить последствия, мы решили создать сайт с JupyterLite для демонстрационных версий на сайте Try Jupyter. Теперь пользователи могут испытывать интерфейсы Jupyter в браузерах, ничего не устанавливая на компьютер. Демо JupyterLab и Jupyter Notebook перенаправляют на новое развёртывание JupyterLite:

Это развёртывание содержит расширение jupyterlab-tour, предоставляющее удобный для новичков обзор интерфейса Jupyter.

Развёртываем сайт с JupyterLite

JupyterLite в отличие от Jupyter обходится без запуска сервера Python и при развёртывании может использоваться как простой статический сайт. Это упрощает развёртывание и сокращает затраты на эксплуатацию. Ниже вы увидите примеры развёртывания JupyterLite и REPL Python.

Развёртываем JupyterLite на GitHub Pages

GitHub Pages — один из самых простых способов размещения сайта с помощью JupyterLite. Посмотрите, на что по умолчанию способен этот демонстрационный репозиторий. За пару кликов и пару минут он позволяет загрузить сайт с JupyterLite и развернуть его на GitHub Pages:

Через считанные минуты сайт будет готов; следующим фрагментом кода вы сможете встроить интерактивную консоль:

<iframe
  src="https://yourhandle.github.io/my-custom-deployment/repl/index.html?kernel=python&toolbar=1"
  width="100%"
  height="500px"
>
</iframe>

Развёртываем сайт на Vercel или Netlify

Хостинг Vercel и Netlify — хороший вариант для развёртывания статического сайта с JupyterLite. REPLite — это пример проекта, развёрнутого в Vercel на основе репозитория с настраиваемой конфигурацией.

Python REPL можно встроить с помощью фрейма HTML:

<iframe src="https://replite.vercel.app/repl?kernel=python&toolbar=1" width="100%" height="100%">
</iframe>

Чтобы при запуске автоматически выбрать ядро Python, здесь применяется параметр URL ?kernel=python.

Развёртываем JupyterLite на ReadTheDocs с помощью расширения Sphinx

jupyterlite-sphinx привносит в документацию Sphinx максимум возможностей JupyterLite. Он автоматически развёртывает JupyterLite на сайте документации и предоставляет утилиты, которые упрощают использование этого развёртывания.

Если вы разработчик, то это очень удобный инструмент, позволяющий пользователям тестировать вашу библиотеку прямо на странице документации. Он пригодится пользователям Jupyter, чтобы легко выкладывать результаты работы на readthedocs.org, GitHub Pages или любом другом хосте с поддержкой документации Sphinx.

Установка

С помощью pip устанавливаем jupyterlite-sphinx:

pip install jupyterlite-sphinx

В файл conf.py добавляем расширение:

extensions = [
    'jupyterlite_sphinx',
    # And other sphinx extensions
    # ...
]

Вот и всё. Благодаря jupyterlite-sphinx сайт с JupyterLite развёртывается автоматически, при создании документов со Sphinx.

Применение

В jupyterlite-sphinx есть ряд директив Sphinx, чтобы встраивать консоли Python и пользовательские блокноты в документацию.

Чтобы встроить REPL, аналогичную NumPy.org, напишите:

.. replite::
   :kernel: python
   :theme: JupyterLab Light
   :width: 100%
   :height: 600px
    print('Hello from a JupyterLite console!')

Чтобы встроить полноценный блокнот:

.. retrolite:: my_notebook.ipynb

И вот код для встраивания полноценного пользовательского интерфейса JupyterLite:

.. jupyterlite::

Блокноты сохраняются в локальном хранилище браузера, поэтому любая выполненная работа может быть извлечена позже, когда вы вернётесь на страницу.

Документация

Документация jupyterlite-sphinx с интерактивными примерами находится здесь.

Вот пример использования jupyterlite-sphinx в ReadTheDocs.

Другие примеры

JupyterLite развёртывается практически на всех работающих со статическими файлами платформах. Чтобы больше узнать о развёртывании JupyterLite на других платформах, загляните в документацию.

Jupyter повсюду

В связи с быстрым распространением JupyterLite на очень посещаемых сайтах, таких как numpy.org и try.jupyter.org, мы прогнозируем освоение Jupyter и на других сайтах и документации в ближайшие месяцы. С помощью Jupyter мы надеемся донести интерактивные вычисления до ещё большего числа людей и сделать их доступнее за счёт снижения порога входа.

Функциональность JupyterLite легко расширяется, поэтому мы также ожидаем увеличения количества развёртываний и приложений на основе Jupyter, что позволит многократно и эффективно использовать компоненты динамичной экосистемы Jupyter.

Jupyter не зависит от языка, и сегодня в JupyterLite доступно больше ядер, например, для Lua и SQLite — ядра на основе фреймворка Xeus. Скоро в Jupyter появится поддержка документации и сайтов не только на Python.

А пока в Jupyter добавляют новые ядра, мы поможем вам прокачать скиллы или освоить профессию в IT, востребованную в любое время:

• Профессия Data Scientist

• Профессия Fullstack-разработчик на Python

Выбрать другую востребованную профессию.