Создание расширения Jupyter Notebook

В этом руководстве показано, как создать расширение Jupyter Notebook в Azure Data Studio. Расширение поставляет пример Jupyter Notebook, который можно открыть и запустить в Azure Data Studio.

В этой статье раскрываются следующие темы:

  • Создание проекта расширения.
  • Установка генератора расширений.
  • Создание расширения записных книжек.
  • Запуск расширения.
  • Упакуйте расширение.
  • Опубликуйте расширение в Marketplace.

Используемые API

  • azdata.nb.showNotebookDocument

Варианты использования расширения

Есть несколько причин, чтобы создать расширение записных книжек:

  • совместное использование интерактивной документации;
  • сохранение этой записной книжки и постоянный доступ к ней;
  • предоставление пользователям информации о проблемах написания кода;
  • управление версиями и отслеживание обновлений записных книжек.

Предварительные требования

Средство Azure Data Studio основано на той же платформе, что и Visual Studio Code, поэтому расширения для Azure Data Studio создаются с помощью Visual Studio Code. Чтобы приступить к работе, вам потребуются следующие компоненты.

  • Установленный Node.js, доступный в вашей переменной $PATH. Node.js включает в себя npm, диспетчер пакетов Node.js, который будет использоваться для установки генератора расширений.
  • Visual Studio Code для отладки расширения.
  • Убедитесь, что azuredatastudio указан в вашем пути. Для Windows выберите параметр Добавить в PATH в setup.exe. Для Mac или Linux выполните команду Install 'azuredatastudio' command in PATH из палитры команд в Azure Data Studio.

Установка генератора расширений

Чтобы упростить процесс создания расширений, мы создали генератор расширений с помощью Yeoman. Для его установки выполните следующую команду в командной строке:

npm install -g yo generator-azuredatastudio

Создание расширения

Для создания расширения сделайте следующее.

  1. Запустите генератор расширений с помощью следующей команды:

    yo azuredatastudio

  2. Выберите Новые записные книжки (отдельные) в списке типов расширений.

    Генератор расширений записных книжек

  3. Выполните инструкции, чтобы ввести имя расширения. Мы будем использовать имя Test Notebook. Затем введите имя издателя. Здесь мы используем имя Microsoft. В последнюю очередь добавьте описание.

Теперь здесь есть несколько ветвей. Можно добавить уже созданные записные книжки Jupyter Notebook или использовать образцы записных книжек, предоставленные в генераторе.

В этом учебнике мы будем использовать пример записной книжки Python:

Выбор примера Python

Если у вас есть записные книжки, которые вы хотите отправить, укажите это в ответе. Укажите абсолютный путь к файлу, где находятся все записные книжки или файлы Markdown.

При выполнении предыдущих шагов создается папка с примером записной книжки. Откройте ее в Visual Studio Code, чтобы предоставить расширение записных книжек.

Изучение расширения

В настоящее время ваш проект должен выглядеть следующим образом:

Структура файла расширения

Файл vsc-extension-quickstart.md предоставляет ссылку на важные файлы. В файле README.md можно предоставить документацию для нового расширения. Обратите внимание на файлы package.json, notebook.ts и pySample.ipynb.

Если у вас есть файлы или папки, которые не нужно публиковать, включите их имена в файл .vscodeignore.

Давайте взглянем на notebook.ts, чтобы понять, что делает новое расширение.

// This function is called when you run the command `Launch Notebooks: Test Notebook` from the
// command palette in Azure Data Studio. If you want any additional functionality
// to occur when you launch the book, add it to the activate function.
export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(vscode.commands.registerCommand('launchNotebooks.test-notebook', () => {
        let notebooksToDisplay: Array<string> = processNotebooks();
        notebooksToDisplay.forEach(name => {
            azdata.nb.showNotebookDocument(vscode.Uri.file(name));
        });
    }));

    // Add other code here if you want to register another command.
}

Это главная функция в notebook.ts, которая вызывается при каждом запуске расширения с помощью команды Запуск записных книжек: Test Notebook. Мы создаем новую команду с помощью API vscode.commands.registerCommand. Следующее определение внутри фигурных скобок — это код, который выполняется при каждом вызове команды. Каждую записную книжку, найденную функцией processNotebooks, можно открыть в Azure Data Studio с помощью azdata.nb.showNotebookDocument.

Файл package.json также играет важную роль при регистрации команды "Запуск записных книжек": Test Notebook.

"activationEvents": [
        "onCommand:launchNotebooks.test-notebook"
    ],
    "main": "./out/notebook.js",
    "contributes": {
        "commands": [
            {
                "command": "launchNotebooks.test-notebook",
                "title": "Launch Notebooks: Test Notebook"
            }
        ]
    }

У нас есть событие активации для команды, и мы добавили определенные точки вклада. Они отображаются в разделе вашего расширения в Marketplace, где публикуются расширения. Если вы хотите добавить дополнительные команды, укажите их в поле activationEvents. Дополнительные параметры см. в разделе События активации.

Упаковка расширения

Чтобы предоставить общий доступ другим пользователям, нужно упаковать расширение в один файл. Его можно опубликовать в магазине Marketplace расширений Azure Data Studio или предоставить для общего доступа другим участникам команды или сообщества. Для этого нужно установить другой пакет npm из командной строки.

npm install -g vsce

Внесите в файл README.md желаемые изменения. Затем перейдите к базовому каталогу расширения и выполните команду vsce package. При необходимости можно связать репозиторий с расширением или продолжить работу без него. Чтобы добавить его, добавьте аналогичную строку в файл package.json.

"repository": {
    "type": "git",
    "url": "https://github.com/laurajjiang/testnotebook.git"
}

После добавления этих строк создается файл my test-notebook-0.0.1.vsix, готовый для установки и публикации.

Запуск расширения

Чтобы запустить и проверить расширение, перейдите в Azure Data Studio и откройте палитру команд, нажав клавиши Ctrl+Shift+P. Найдите команду Расширения: установка из VSIX и перейдите к папке, содержащей новое расширение.

Установка VSIX

Расширение должно отображаться на панели расширения в Azure Data Studio. Снова откройте палитру команд, и вы увидите новую команду, созданную с помощью нашего расширения, Запуск книги: Test Book. После запуска откроется книга Jupyter Book, упакованная с нашим расширением.

Записная книжка — команда

Поздравляем! Вы создали свое первое расширение Jupyter Notebook и теперь можете предоставить его.

Публикация расширения в Marketplace

Магазин Marketplace расширений Azure Data Studio пока находится в стадии разработки. Для публикации разместите VSIX-файл расширения в любом расположении, например на странице выпуска GitHub. Затем следует отправить запрос на вытягивание, который обновляет этот JSON-файл, добавляя в него сведения о расширении.

Дальнейшие действия

В этом руководстве вы узнали, как выполнять следующие задачи:

  • Создание проекта расширения.
  • Установка генератора расширений.
  • Создание расширения записных книжек.
  • Создание расширения.
  • Упаковка расширения.
  • Публикация расширения в Marketplace.

Мы надеемся, что после ознакомления с этой статьей вы захотите создать собственное расширение для Azure Data Studio.

Если у вас появилась идея, но вы не знаете, с чего начать, откройте вопрос или отправьте твит нашей команде: azuredatastudio.

Для получения дополнительных сведений можно обратиться к руководству по расширениям Visual Studio Code, которое охватывает все существующие API и шаблоны.