Vytvoření rozšíření Jupyter Book

Článek
10/16/2024

Tento kurz ukazuje, jak vytvořit nové rozšíření Jupyter Book Azure Data Studio. Rozšíření dodává ukázkovou knihu Jupyter, kterou je možné otevřít a spustit v nástroji Azure Data Studio.

V tomto článku získáte informace o těchto tématech:

Vytvořte projekt rozšíření.
Nainstalujte generátor rozšíření.
Vytvořte rozšíření Jupyter Book.
Spusťte rozšíření.
Zabalte rozšíření.
Publikujte své rozšíření na marketplace.

Použitá rozhraní API

bookTreeView.openBook

Případy použití rozšíření

Existuje několik různých důvodů, proč byste vytvořili rozšíření Jupyter Book:

Sdílení uspořádané a rozdělené interaktivní dokumentace
Sdílejte úplnou knihu (podobně jako elektronická kniha, ale distribuovaná prostřednictvím nástroje Azure Data Studio)
Verze a sledování aktualizací Jupyter Booku

Hlavním rozdílem mezi aplikací Jupyter Book a rozšířením poznámkového bloku je to, že vám Jupyter Book poskytuje organizaci. Desítky poznámkových bloků je možné rozdělit do různých kapitol v Jupyter Booku, ale rozšíření poznámkového bloku je určené k odeslání malého počtu jednotlivých poznámkových bloků.

Požadavky

Azure Data Studio je postavené na stejné platformě jako Visual Studio Code, takže rozšíření pro Azure Data Studio se vytvářejí pomocí editoru Visual Studio Code. Abyste mohli začít, potřebujete následující komponenty:

Node.js nainstalované a dostupné ve vašem $PATHsouboru . Node.js zahrnuje npm, Node.js Správce balíčků, který se používá k instalaci generátoru rozšíření.
Visual Studio Code pro provedení jakýchkoli změn rozšíření a ladění rozšíření.
Ujistěte se azuredatastudio , že je ve vaší cestě. V systému Windows nezapomeňte v setup.exe zvolit možnost Přidat do cesty . Pro Mac nebo Linux spusťte příkaz Install 'azuredatastudio' v PATH z palety příkazů v Nástroji Azure Data Studio.

Instalace generátoru rozšíření

Abychom zjednodušili proces vytváření rozšíření, vytvořili jsme generátor rozšíření pomocí Yeomanu. Pokud ho chcete nainstalovat, spusťte z příkazového řádku následující příkaz:

npm install -g yo generator-azuredatastudio

Vytvoření rozšíření

Vytvoření rozšíření:

Spusťte generátor rozšíření pomocí následujícího příkazu:

yo azuredatastudio
V seznamu typů rozšíření zvolte Nový Jupyter Book .
Podle pokynů vyplňte název rozšíření. Pro účely tohoto kurzu použijte testovací knihu. Pak vyplňte název vydavatele. Pro účely tohoto kurzu použijte Microsoft. Nakonec přidejte popis.

Můžete buď zadat existující Jupyter Book, použít zadanou ukázkovou knihu nebo vytvořit novou knihu Jupyter Book. Zobrazí se všechny tři možnosti.

Zadání existující knihy

Pokud chcete odeslat knihu, kterou jste už vytvořili, zadejte absolutní cestu k souboru do složky, ve které je obsah knihy živý. Pak můžete být připraveni přejít na další informace o rozšíření a jeho expedici.

Snímek obrazovky znázorňující existující knihu

Použití ukázkové knihy

Pokud nemáte existující knihu nebo poznámkové bloky, můžete použít poskytnutou ukázku v generátoru.

Snímek obrazovky znázorňující ukázkovou knihu Jupyter

Ukázková kniha ukazuje, jak vypadá jednoduchá kniha Jupyter Book. Pokud se chcete dozvědět o přizpůsobení Jupyter Booku, přečtěte si následující část o tom, jak vytvořit novou knihu s existujícími poznámkovými bloky.

Vytvoření nové knihy

Pokud máte poznámkové bloky, které chcete zabalit do Jupyter Booku, můžete. Generátor se zeptá, jestli chcete kapitoly v knize, a pokud ano, kolik a jejich titulů. Tady vidíte, jak proces výběru vypadá. Pomocí mezerníku vyberte, které poznámkové bloky chcete umístit do každé kapitoly.

Snímek obrazovky znázorňující vytvoření knihy Jupyter

Dokončením předchozích kroků vytvoříte novou složku s novou aplikací Jupyter Book. Otevřete složku v editoru Visual Studio Code a jste připraveni odeslat rozšíření Jupyter Book.

Vysvětlení rozšíření

Projekt by teď měl vypadat takto:

Snímek obrazovky znázorňující strukturu souboru přípony

Soubor vsc-extension-quickstart.md obsahuje odkaz na důležité soubory. Soubor README.md je místo, kde můžete poskytnout dokumentaci pro nové rozšíření. Všimněte si , package.jsonjupyter-book.ts, contenta toc.yml soubory. Složka content obsahuje všechny soubory poznámkového bloku nebo markdownu. Struktury toc.yml jupyter Book a automaticky se vygenerují, pokud jste se rozhodli vytvořit vlastní Jupyter Book prostřednictvím generátoru rozšíření.

Pokud jste vytvořili knihu pomocí generátoru a rozhodli jste se pro kapitoly v knize, struktura složek by vypadala trochu jinak. Místo souborů Markdown a Jupyter Notebook, které se nachází ve content složce, budou existovat podsložky, které odpovídají názvům, které jste zvolili pro své kapitoly.

Pokud nějaké soubory nebo složky, které nechcete publikovat, můžete do .vscodeignore souboru zahrnout jejich názvy.

Pojďme se podívat, jupyter-book.ts co dělá naše nově vytvořené rozšíření.

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

Funkce activate je hlavní akcí vašeho rozšíření. Všechny příkazy, které chcete zaregistrovat, by se měly objevit uvnitř activate funkce, podobně jako náš launchBook.test-book příkaz. processNotebooks Uvnitř funkce najdeme složku rozšíření, která obsahuje naši jupyter Book a volání bookTreeView.openBook pomocí složky rozšíření jako parametru.

Soubor package.json také hraje důležitou roli při registraci příkazu rozšíření.

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

Aktivační událost onCommand, aktivuje funkci, kterou jsme zaregistrovali při vyvolání příkazu. Existuje několik dalších aktivačních událostí, které jsou možné pro další přizpůsobení. Další informace najdete v tématu Události aktivace.

Zabalení rozšíření

Pokud chcete sdílet s ostatními, musíte příponu zabalit do jednoho souboru. Vaše rozšíření můžete publikovat na marketplace rozšíření Azure Data Studio nebo sdílet s týmem nebo komunitou. Pokud chcete tento krok provést, musíte z příkazového řádku nainstalovat další balíček npm.

npm install -g vsce

README.md Upravte soubor podle svých představ. Pak přejděte do základního adresáře rozšíření a spusťte vsce packagepříkaz . Volitelně můžete propojit úložiště s rozšířením nebo pokračovat bez tohoto úložiště. Pokud ho chcete přidat, přidejte do souboru podobný řádek package.json .

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

Po přidání my test-book-0.0.1.vsix těchto řádků se vytvoří soubor připravený k instalaci v nástroji Azure Data Studio.

Spuštění rozšíření

Pokud chcete rozšíření spustit a otestovat, otevřete Azure Data Studio a otevřete paletu příkazů stisknutím kombinace kláves Ctrl+Shift+P. Vyhledejte příkaz Rozšíření: Nainstalujte z VSIX a přejděte do složky, která obsahuje vaše nové rozšíření. Teď by se měl zobrazit na panelu rozšíření v Nástroji Azure Data Studio.

Snímek obrazovky znázorňující instalaci VSIX

Znovu otevřete paletu příkazů a najděte příkaz, který jsme zaregistrovali, spustit knihu: Testovací poznámkový blok. Po spuštění by měl otevřít Jupyter Book, který jsme zabalili s naším rozšířením.

Snímek obrazovky znázorňující příkaz notebook-command

Gratulujeme! Vytvořili jste a teď můžete dodávat své první rozšíření Jupyter Book. Další informace o Jupyter Books naleznete v tématu Knihy s Jupyter.

Publikování rozšíření na Marketplace

Marketplace rozšíření Azure Data Studio probíhá ve výstavby. Pokud chcete publikovat, hostujte rozšíření VSIX někde, například na stránce verze GitHubu. Odešlete žádost o přijetí změn, která aktualizuje tento soubor JSON informacemi o rozšíření.

Další kroky

V tomto kurzu jste se naučili, jak:

Vytvořte projekt rozšíření.
Nainstalujte generátor rozšíření.
Vytvořte rozšíření Jupyter Book.
Zabalte rozšíření.
Publikujte své rozšíření na marketplace.

Doufáme, že po přečtení tohoto článku budete mít nápady na Jupyter Books, které chcete sdílet s komunitou azure Data Studio.

Pokud máte nápad, ale nevíte, jak začít, otevřete problém nebo tweetujte tým v azuredatastudio.

Další informace najdete v průvodci rozšířením editoru Visual Studio Code, který obsahuje všechna existující rozhraní API a vzory.

Sdílet prostřednictvím