Skapa ett Jupyter Book-tillägg

Den här självstudien visar hur du skapar ett nytt Jupyter Book Azure Data Studio-tillägg. Tillägget skickar ett exempel på En Jupyter Book som kan öppnas och köras i Azure Data Studio.

I den här artikeln lär du dig hur du:

• Skapa ett tilläggsprojekt.
• Installera tilläggsgeneratorn.
• Skapa jupyterbokstillägget.
• Kör tillägget.
• Paketera tillägget.
• Publicera ditt tillägg på Marketplace.

API:er som används

• bookTreeView.openBook

Användningsfall för tillägg

Det finns några olika orsaker till varför du skulle skapa ett Jupyter Book-tillägg:

• Dela organiserad och uppdelad interaktiv dokumentation
• Dela en fullständig bok (liknar en e-bok men distribueras via Azure Data Studio)
• Version och hålla reda på Jupyter Book-uppdateringar

Den största skillnaden mellan en Jupyter Book och ett notebook-tillägg är att en Jupyter Book ger dig organisation. Tiotals notebook-filer kan delas upp i olika kapitel i en Jupyter-bok, men notebook-tillägget är avsett att skicka ett litet antal enskilda notebook-filer.

Förutsättningar

Azure Data Studio bygger på samma ramverk som Visual Studio Code, så tillägg för Azure Data Studio skapas med hjälp av Visual Studio Code. För att komma igång behöver du följande komponenter:

• Node.js installerat och tillgängligt i .$PATH Node.js innehåller npm, Node.js Package Manager, som används för att installera tilläggsgeneratorn.
• Visual Studio Code för att göra ändringar i tillägget och felsöka tillägget.
• Se till att azuredatastudio är i din sökväg. För Windows måste du välja alternativet Lägg till i sökväg i setup.exe. För Mac eller Linux kör du kommandot Installera "azuredatastudio" i PATH från kommandopaletten i Azure Data Studio.

Installera tilläggsgeneratorn

För att förenkla processen med att skapa tillägg har vi skapat en tilläggsgenerator med Hjälp av Yeoman. Installera det genom att köra följande kommando från kommandotolken:

npm install -g yo generator-azuredatastudio

Skapa ditt tillägg

Så här skapar du ett tillägg:

1. Starta tilläggsgeneratorn med följande kommando:

   yo azuredatastudio

2. Välj Ny Jupyter-bok i listan över tilläggstyper.

   

3. Följ stegen för att fylla i tilläggsnamnet. I den här självstudien använder du Testbok. Fyll sedan i ett utgivarnamn. I den här självstudien använder du Microsoft. Lägg slutligen till en beskrivning.

Du väljer att antingen ange en befintlig Jupyter Book, använda en angivet exempelbok eller arbeta för att skapa en ny Jupyter Book. Alla tre alternativen visas.

Ange en befintlig bok

Om du vill skicka en bok som du redan har skapat anger du den absoluta filsökvägen till mappen där bokinnehållet finns. Du kan sedan vara redo att gå vidare till att lära dig om tillägget och skicka det.

Använda exempelboken

Om du inte har någon befintlig bok eller anteckningsböcker kan du använda det angivna exemplet i generatorn.

Exempelboken visar hur en enkel Jupyter Book ser ut. Om du vill lära dig mer om hur du anpassar en Jupyter-bok kan du läsa följande avsnitt om hur du skapar en ny bok med befintliga anteckningsböcker.

Skapa en ny bok

Om du har anteckningsböcker som du vill paketera i en Jupyter Book kan du göra det. Generatorn frågar om du vill ha kapitel i din bok, och i så fall hur många och deras titlar. Du kan se hur urvalsprocessen ser ut här. Använd blanksteget för att välja vilka anteckningsböcker du vill placera i varje kapitel.

När du slutför föregående steg skapas en ny mapp med din nya Jupyter Book. Öppna mappen i Visual Studio Code så är du redo att skicka Jupyter Book-tillägget.

Förstå tillägget

Så här bör ditt projekt för närvarande se ut:

Filen vsc-extension-quickstart.md innehåller en referens till de viktiga filerna. I README.md filen kan du ange dokumentation för det nya tillägget. package.jsonObservera filerna , jupyter-book.ts, contentoch toc.yml . Mappen content innehåller alla notebook- eller markdown-filer. Strukturerar toc.yml jupyterboken och genereras automatiskt om du väljer att skapa en anpassad Jupyter Book via tilläggsgeneratorn.

Om du skapade en bok med hjälp av generatorn och valde kapitel i din bok skulle mappstrukturen se lite annorlunda ut. I stället för dina Markdown- och Jupyter Notebook-filer som finns i content mappen, skulle det finnas undermappar som motsvarar de rubriker som du har valt för dina kapitel.

Om det finns filer eller mappar som du inte vill publicera kan du inkludera deras namn i .vscodeignore filen.

Låt oss ta en titt på jupyter-book.ts för att förstå vad vårt nybildade tillägg gör.

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

Funktionen activate är huvudåtgärden för tillägget. Alla kommandon som du vill registrera ska visas i activate funktionen, ungefär som vårt launchBook.test-book kommando. processNotebooks I funktionen hittar vi vår tilläggsmapp som innehåller jupyterboken och anropar bookTreeView.openBook med hjälp av vårt tilläggsmapp som en parameter.

Filen package.json spelar också en viktig roll när det gäller att registrera vårt tilläggskommando.

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

Aktiveringshändelsen, onCommand, utlöser den funktion som vi registrerade när vi anropade kommandot. Det finns några andra aktiveringshändelser som är möjliga för ytterligare anpassning. Mer information finns i Aktiveringshändelser.

Paketera tillägget

Om du vill dela med andra måste du paketera tillägget i en enda fil. Ditt tillägg kan publiceras på Marknadsplatsen för Azure Data Studio-tillägget eller delas med ditt team eller din community. För att göra det här steget måste du installera ett annat npm-paket från kommandoraden.

npm install -g vsce

README.md Redigera filen efter behov. Gå sedan till baskatalogen för tillägget och kör vsce package. Du kan också länka en lagringsplats med ditt tillägg eller fortsätta utan en. Lägg till en rad som liknar din package.json fil om du vill lägga till en rad.

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

När dessa rader har lagts till skapas en my test-book-0.0.1.vsix fil som är redo att installeras i Azure Data Studio.

Kör tillägget

Om du vill köra och testa tillägget öppnar du Azure Data Studio och öppnar kommandopaletten genom att välja Ctrl+Skift+P. Leta upp kommandotilläggen : Installera från VSIX och gå till mappen som innehåller det nya tillägget. Den bör nu visas i tilläggspanelen i Azure Data Studio.

Öppna kommandopaletten igen och leta reda på kommandot som vi registrerade, Starta bok: Testa notebook-fil. När den körs bör den öppna Jupyter Book som vi paketerade med vårt tillägg.

Grattis! Du har skapat och kan nu skicka ditt första Jupyter Book-tillägg. Mer information om Jupyter Books finns i Böcker med Jupyter.

Publicera ditt tillägg på Marketplace

Marknadsplatsen för Azure Data Studio-tillägget håller på att byggas. Om du vill publicera är du värd för tillägget VSIX någonstans, till exempel på en GitHub-versionssida. Skicka en pull-begäran som uppdaterar den här JSON-filen med tilläggsinformationen.

Nästa steg

I den här självstudiekursen lärde du dig att:

• Skapa ett tilläggsprojekt.
• Installera tilläggsgeneratorn.
• Skapa jupyterbokstillägget.
• Paketera tillägget.
• Publicera ditt tillägg på Marketplace.

Vi hoppas att du efter att ha läst den här artikeln har idéer om Jupyter Books som du vill dela med Azure Data Studio-communityn.

Om du har en idé men inte vet hur du kommer igång öppnar du ett problem eller tweetar teamet på azuredatastudio.

Mer information finns i tilläggsguiden för Visual Studio Code som omfattar alla befintliga API:er och mönster.