Поделиться через

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

Важный

Azure Data Studio будет выведена из эксплуатации 28 февраля 2026 г.. Мы рекомендуем использовать Visual Studio Code. Дополнительные сведения о миграции в Visual Studio Code см. в Что происходит с Azure Data Studio?

В этом руководстве показано, как создать расширение 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 в списке типов расширений.

    Снимок экрана, на котором показан генератор расширений.

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

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

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

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

Снимок экрана, показывающий существующую книгу.

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

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

Снимок экрана, на котором показан пример книги Jupyter Book.

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

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

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

Снимок экрана: создание Jupyter Book.

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

Понять ваше расширение

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

Снимок экрана, на котором показана структура файла расширения.

Файл 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.

Снимок экрана, на котором показана установка VSIX.

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

Снимок экрана, на котором отображается команда notebook-command.

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

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

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

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

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

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

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

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

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