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

  • Статья

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

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

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

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

  • bookTreeView.openBook

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

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

  • совместное использование упорядоченной и разбитой на разделы интерактивной документации;
  • совместное использование полной книги (аналогично электронной книге, но с распределением по Azure Data Studio);
  • управление версиями и отслеживание обновлений Jupyter Book.

Основное различие между Jupyter Book и расширением записной книжки состоит в том, что Jupyter Book предоставляет организацию. Десятки записных книжек можно разделить на разные главы в Jupyter Book, но расширение записных книжек предназначено для доставки небольшого количества отдельных записных книжек.

Необходимые компоненты

Средство 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. Выберите Создать Jupyter Book в списке типов расширений.

    Screenshot that shows the extension generator.

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

Вы хотите предоставить существующую книгу Jupyter Book, использовать предоставленный образец книги или создать новую книгу Jupyter Book. Показаны все три варианта.

Предоставление существующей книги

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

Screenshot that shows an existing book.

Использование образца книги

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

Screenshot that shows a sample Jupyter book.

В образце книги показано, как выглядит простая книга Jupyter Book. Если вы хотите узнать о настройке книги Jupyter Book, см. следующий раздел о создании новой книги с существующими записными книжками.

Создание новой книги

Если у вас есть записные книжки, которые вы хотите упаковать в книгу Jupyter Book, вы можете это сделать. Генератор спрашивает, должны ли в книге быть главы, и, если да, сколько их будет и как они будут называться. Здесь показано, как выглядит процесс выбора. С помощью клавиши пробела выберите, какие записные книжки нужно поместить в каждую главу.

Screenshot that shows creating Jupyter book.

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

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

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

Screenshot that shows an extension file structure.

Файл vsc-extension-quickstart.md предоставляет ссылку на важные файлы. В файле README.md можно предоставить документацию для нового расширения. Обратите внимание на файлы package.json, jupyter-book.ts, content и toc.yml. Папка content содержит все файлы записных книжек или Markdown. toc.yml структурирует книгу Jupyter Book и формируется автоматически, если вы решили создать настраиваемую книгу Jupyter Book с помощью генератора расширений.

Если вы создали книгу с помощью генератора и выбрали главы в книге, структура папок будет выглядеть немного иначе. Вместо файлов Markdown и Jupyter Notebook, которые находятся в папке content, у вас будут вложенные папки, соответствующие заголовкам, выбранным для глав.

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

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

// This function is called when you run the command `Launch Book: Test Book` 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('launchBook.test-book', () => {
        processNotebooks();
    }));

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

Функция activate является основным действием вашего расширения. Все команды, которые необходимо зарегистрировать, должны отображаться внутри функции activate аналогично команде launchBook.test-book. В функции processNotebooks находится папка расширения, которая содержит нашу книгу Jupyter Book. Мы вызываем bookTreeView.openBook, используя папку расширения в качестве параметра.

Файл package.json также играет важную роль при регистрации команды расширения.

"activationEvents": [
		"onCommand:launchBook.test-book"
	],
	"main": "./out/notebook.js",
	"contributes": {
		"commands": [
			{
				"command": "launchBook.test-book",
				"title": "Launch Book: Test Book"
			}
		]
	}

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

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

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

npm install -g vsce

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

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

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

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

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

Screenshot that shows installing VSIX.

Откройте палитру команд еще раз и найдите команду, которую мы зарегистрировали, Launch Book: Test Notebook. После запуска откроется книга Jupyter Book, упакованная с нашим расширением.

Screenshot that shows the notebook-command.

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

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

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

Следующие шаги

Из этого руководства вы узнали, как:

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

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

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

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