Udostępnij za pośrednictwem

Tworzenie rozszerzenia książki Jupyter

  • Artykuł

W tym samouczku pokazano, jak utworzyć nowe rozszerzenie programu Jupyter Book usługi Azure Data Studio. Rozszerzenie dostarcza przykładową książkę Jupyter, którą można otworzyć i uruchomić w narzędziu Azure Data Studio.

W tym artykule omówiono sposób wykonywania następujących zadań:

  • Utwórz projekt rozszerzenia.
  • Zainstaluj generator rozszerzeń.
  • Utwórz rozszerzenie książki Jupyter.
  • Uruchom rozszerzenie.
  • Spakuj rozszerzenie.
  • Opublikuj rozszerzenie na platformie handlowej.

Używane interfejsy API

  • bookTreeView.openBook

Przypadki użycia rozszerzeń

Istnieje kilka różnych powodów, dla których można utworzyć rozszerzenie książki Jupyter:

  • Udostępnianie zorganizowanej i podzielonej interaktywnej dokumentacji
  • Udostępnij pełną książkę (podobną do książki e-book, ale dystrybuowanej za pośrednictwem usługi Azure Data Studio)
  • Wersja i śledzenie aktualizacji książek Jupyter

Główną różnicą między książką Jupyter Book a rozszerzeniem notesu jest to, że książka Jupyter zapewnia organizację. Dziesiątki notesów można podzielić na różne rozdziały w książce Jupyter, ale rozszerzenie notesu ma na celu dostarczenie niewielkiej liczby poszczególnych notesów.

Wymagania wstępne

Narzędzie Azure Data Studio jest oparte na tej samej strukturze co program Visual Studio Code, więc rozszerzenia dla programu Azure Data Studio są kompilowane przy użyciu programu Visual Studio Code. Do rozpoczęcia pracy potrzebne są następujące składniki:

  • Node.js zainstalowane i dostępne w pliku $PATH. Node.js obejmuje narzędzie npm, Node.js Menedżer pakietów, które służy do instalowania generatora rozszerzeń.
  • Program Visual Studio Code umożliwia wprowadzanie wszelkich zmian w rozszerzeniu i debugowanie rozszerzenia.
  • Upewnij się, że znajduje się azuredatastudio w ścieżce. W przypadku systemu Windows upewnij się, że w setup.exe wybrano opcję Dodaj do ścieżki . W przypadku komputerów Mac lub Linux uruchom polecenie Zainstaluj "azuredatastudio" w ścieżce PATH z palety poleceń w narzędziu Azure Data Studio.

Instalowanie generatora rozszerzeń

Aby uprościć proces tworzenia rozszerzeń, utworzyliśmy generator rozszerzeń przy użyciu narzędzia Yeoman. Aby go zainstalować, uruchom następujące polecenie w wierszu polecenia:

npm install -g yo generator-azuredatastudio

Tworzenie rozszerzenia

Aby utworzyć rozszerzenie:

  1. Uruchom generator rozszerzeń za pomocą następującego polecenia:

    yo azuredatastudio

  2. Wybierz pozycję Nowa książka Jupyter z listy typów rozszerzeń.

    Zrzut ekranu przedstawiający generator rozszerzeń.

  3. Wykonaj kroki, aby wypełnić nazwę rozszerzenia. Na potrzeby tego samouczka użyj książki testowej. Następnie wprowadź nazwę wydawcy. Na potrzeby tego samouczka użyj firmy Microsoft. Na koniec dodaj opis.

Możesz podać istniejącą książkę Jupyter, użyć dostarczonej przykładowej książki lub utworzyć nową książkę Jupyter. Zostaną wyświetlone wszystkie trzy opcje.

Podaj istniejącą książkę

Jeśli chcesz wysłać już utworzoną książkę, podaj bezwzględną ścieżkę pliku do folderu, w którym znajduje się zawartość książki. Następnie możesz przystąpić do dalszej nauki o rozszerzeniu i wysłaniu go.

Zrzut ekranu przedstawiający istniejącą książkę.

Korzystanie z przykładowej książki

Jeśli nie masz istniejącej książki lub notesów, możesz użyć podanego przykładu w generatorze.

Zrzut ekranu przedstawiający przykładową książkę Jupyter.

Przykładowa książka pokazuje, jak wygląda prosta książka Jupyter. Jeśli chcesz dowiedzieć się więcej na temat dostosowywania książki Jupyter, zobacz następującą sekcję dotyczącą tworzenia nowej książki z istniejącymi notesami.

Tworzenie nowej książki

Jeśli masz notesy, które chcesz spakować do książki Jupyter, możesz. Generator, czy chcesz rozdziały w książce, a jeśli tak, ile i ich tytułów. W tym miejscu możesz zobaczyć, jak wygląda proces wyboru. Użyj paska spacji, aby wybrać notesy, które chcesz umieścić w każdym rozdziale.

Zrzut ekranu przedstawiający tworzenie książki Jupyter.

Wykonanie poprzednich kroków spowoduje utworzenie nowego folderu przy użyciu nowej książki Jupyter. Otwórz folder w programie Visual Studio Code i wszystko jest gotowe do wysłania rozszerzenia Jupyter Book.

Omówienie rozszerzenia

W tym przypadku projekt powinien wyglądać następująco:

Zrzut ekranu przedstawiający strukturę pliku rozszerzenia.

Plik vsc-extension-quickstart.md zawiera odwołanie do ważnych plików. Plik README.md to miejsce, w którym można podać dokumentację nowego rozszerzenia. Zanotuj package.jsonpliki , jupyter-book.ts, contenti toc.yml . Folder content zawiera wszystkie pliki notesu lub znaczników markdown. Struktury toc.yml książki Jupyter Book i są generowane automatycznie, jeśli zdecydujesz się utworzyć niestandardową książkę Jupyter Za pośrednictwem generatora rozszerzeń.

Jeśli książka została utworzona przy użyciu generatora i zdecydowała się na rozdziały w książce, struktura folderów będzie wyglądać nieco inaczej. Zamiast plików markdown i Jupyter Notebook, które znajdują się w content folderze, będą podfoldery odpowiadające tytułom wybranym dla rozdziałów.

Jeśli istnieją pliki lub foldery, których nie chcesz publikować, możesz dołączyć ich nazwy do .vscodeignore pliku.

Przyjrzyjmy się jupyter-book.ts temu, co robi nasze nowo utworzone rozszerzenie.

// 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.
}

Funkcja activate jest główną akcją rozszerzenia. Wszystkie polecenia, które chcesz zarejestrować, powinny być wyświetlane wewnątrz activate funkcji, podobnie jak w przypadku naszego launchBook.test-book polecenia. processNotebooks W funkcji znajdujemy nasz folder rozszerzenia, który zawiera naszą książkę Jupyter Book i wywołujemy bookTreeView.openBook go za pomocą folderu rozszerzenia jako parametru.

Plik package.json odgrywa również ważną rolę w rejestrowaniu polecenia rozszerzenia.

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

Zdarzenie onCommandaktywacji wyzwala funkcję zarejestrowaną podczas wywoływania polecenia. Istnieje kilka innych zdarzeń aktywacji, które są możliwe do dodatkowego dostosowania. Aby uzyskać więcej informacji, zobacz Zdarzenia aktywacji.

Pakowanie rozszerzenia

Aby udostępnić je innym osobom, należy spakować rozszerzenie w jeden plik. Rozszerzenie można opublikować na platformie handlowej rozszerzenia Azure Data Studio lub udostępnić zespołowi lub społeczności. Aby wykonać ten krok, należy zainstalować inny pakiet npm z wiersza polecenia.

npm install -g vsce

Zmodyfikuj README.md plik, aby go polubić. Następnie przejdź do katalogu podstawowego rozszerzenia i uruchom polecenie vsce package. Opcjonalnie możesz połączyć repozytorium z rozszerzeniem lub kontynuować bez tego repozytorium. Aby go dodać, dodaj podobny wiersz do pliku package.json .

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

Po dodaniu tych wierszy zostanie utworzony i gotowy do zainstalowania w narzędziu my test-book-0.0.1.vsix Azure Data Studio.

Uruchamianie rozszerzenia

Aby uruchomić i przetestować rozszerzenie, otwórz narzędzie Azure Data Studio i otwórz paletę poleceń, wybierając Ctrl+Shift+P. Znajdź polecenie Rozszerzenia: Zainstaluj z programu VSIX i przejdź do folderu zawierającego nowe rozszerzenie. Powinien on teraz zostać wyświetlony w panelu rozszerzenia w narzędziu Azure Data Studio.

Zrzut ekranu przedstawiający instalowanie programu VSIX.

Otwórz ponownie paletę poleceń i znajdź zarejestrowane polecenie Launch Book: Test Notebook. Po uruchomieniu należy otworzyć książkę Jupyter, którą spakowaliśmy z naszym rozszerzeniem.

Zrzut ekranu przedstawiający polecenie notebook-.

Gratulacje! Skompilujesz i możesz teraz wysłać swoje pierwsze rozszerzenie Jupyter Book. Aby uzyskać więcej informacji na temat książek Jupyter, zobacz Książki z jupyterem.

Publikowanie rozszerzenia w witrynie Marketplace

Platforma handlowa rozszerzeń usługi Azure Data Studio jest w budowie. Aby opublikować, hostuj rozszerzenie VSIX gdzieś, na przykład na stronie wydania usługi GitHub. Prześlij żądanie ściągnięcia, które aktualizuje ten plik JSON przy użyciu informacji o rozszerzeniu.

Następne kroki

W tym samouczku zawarto informacje na temat wykonywania następujących czynności:

  • Utwórz projekt rozszerzenia.
  • Zainstaluj generator rozszerzeń.
  • Utwórz rozszerzenie książki Jupyter.
  • Spakuj rozszerzenie.
  • Opublikuj rozszerzenie na platformie handlowej.

Mamy nadzieję, że po przeczytaniu tego artykułu będziesz mieć pomysły na książki Jupyter Books, które chcesz udostępnić społeczności usługi Azure Data Studio.

Jeśli masz pomysł, ale nie wiesz, jak rozpocząć pracę, otwórz problem lub tweet zespołu w witrynie azuredatastudio.

Aby uzyskać więcej informacji, przewodnik rozszerzenia programu Visual Studio Code obejmuje wszystkie istniejące interfejsy API i wzorce.