Een Jupyter Book-extensie maken

In deze zelfstudie ziet u hoe u een nieuwe Jupyter Book Azure Data Studio-extensie maakt. De extensie verzendt een jupyter-voorbeeldboek dat kan worden geopend en uitgevoerd in Azure Data Studio.

In dit artikel leert u het volgende:

• Maak een extensieproject.
• Installeer de extensiegenerator.
• Maak uw Jupyter Book-extensie.
• Voer de extensie uit.
• Pak uw extensie in.
• Publiceer uw extensie naar de marketplace.

GEBRUIKTE API's

• bookTreeView.openBook

Gebruiksvoorbeelden voor extensies

Er zijn een aantal verschillende redenen waarom u een Jupyter Book-extensie zou maken:

• Interactieve documentatie over georganiseerde en secties delen
• Een volledig boek delen (vergelijkbaar met een e-book, maar gedistribueerd via Azure Data Studio)
• Versie en houd updates van Jupyter Book bij

Het belangrijkste verschil tussen een Jupyter Book en een notebook-extensie is dat een Jupyter Book u een organisatie biedt. Tientallen notitieblokken kunnen worden gesplitst in verschillende hoofdstukken in een Jupyter Book, maar de extensie van het notitieblok is bedoeld om een klein aantal afzonderlijke notitieblokken te verzenden.

Vereisten

Azure Data Studio is gebouwd op hetzelfde framework als Visual Studio Code, dus extensies voor Azure Data Studio worden gebouwd met behulp van Visual Studio Code. U hebt de volgende onderdelen nodig om aan de slag te gaan:

• Node.js geïnstalleerd en beschikbaar in uw $PATH. Node.js bevat npm, de Node.js Pakketbeheer, die wordt gebruikt om de extensiegenerator te installeren.
• Visual Studio Code om wijzigingen aan te brengen in uw extensie en fouten in de extensie op te sporen.
• Zorg ervoor dat azuredatastudio deze zich in uw pad bevindt. Voor Windows moet u de optie Toevoegen aan pad kiezen in setup.exe. Voer voor Mac of Linux de opdracht 'azuredatastudio' installeren uit in PATH vanuit het opdrachtpalet in Azure Data Studio.

De extensiegenerator installeren

Om het proces van het maken van extensies te vereenvoudigen, hebben we een extensiegenerator gemaakt met behulp van Yeoman. Voer de volgende opdracht uit vanaf de opdrachtprompt om deze te installeren:

npm install -g yo generator-azuredatastudio

Uw extensie maken

Een extensie maken:

1. Start de extensiegenerator met de volgende opdracht:

   yo azuredatastudio

2. Kies Nieuw Jupyter Book in de lijst met extensietypen.

   

3. Volg de stappen om de extensienaam in te vullen. Gebruik Test Book voor deze zelfstudie. Vul vervolgens de naam van een uitgever in. Gebruik Microsoft voor deze zelfstudie. Voeg ten slotte een beschrijving toe.

U selecteert ervoor om een bestaand Jupyter-boek op te geven, een opgegeven voorbeeldboek te gebruiken of om een nieuw Jupyter-boek te maken. Alle drie de opties worden weergegeven.

Een bestaand boek opgeven

Als u een boek wilt verzenden dat u al hebt gemaakt, geeft u het absolute bestandspad op naar de map waarin de inhoud van uw boek zich bevindt. Vervolgens kunt u verdergaan met het leren over de extensie en het verzenden ervan.

Het voorbeeldboek gebruiken

Als u geen bestaand boek of notitieblok hebt, kunt u het opgegeven voorbeeld in de generator gebruiken.

In het voorbeeldboek ziet u hoe een eenvoudig Jupyter-boek eruitziet. Als u meer wilt weten over het aanpassen van een Jupyter Book, raadpleegt u de volgende sectie over het maken van een nieuw boek met bestaande notitieblokken.

Een nieuw boek maken

Als u notitieblokken hebt die u in een Jupyter Book wilt verpakken, kunt u dat doen. De generator vraagt of u hoofdstukken in uw boek wilt, en zo ja, hoeveel en hun titels. Hier ziet u hoe het selectieproces eruitziet. Gebruik de spatiebalk om te selecteren welke notitieblokken u in elk hoofdstuk wilt plaatsen.

Als u de vorige stappen uitvoert, wordt er een nieuwe map gemaakt met uw nieuwe Jupyter Book. Open de map in Visual Studio Code en u bent klaar om uw Jupyter Book-extensie te verzenden.

Meer informatie over uw extensie

Dit is hoe uw project er op dit moment uit moet zien:

Het vsc-extension-quickstart.md bestand bevat een verwijzing naar de belangrijke bestanden. In het README.md bestand kunt u documentatie opgeven voor uw nieuwe extensie. Noteer de package.json, jupyter-book.ts, contenten toc.yml bestanden. De content map bevat alle notebook- of Markdown-bestanden. De toc.yml structuren van uw Jupyter Book en worden automatisch gegenereerd als u ervoor hebt gekozen om een aangepast Jupyter Book te maken via de extensiegenerator.

Als u een boek hebt gemaakt met behulp van de generator en hebt gekozen voor hoofdstukken in uw boek, ziet uw mapstructuur er iets anders uit. In plaats van uw Markdown- en Jupyter Notebook-bestanden in de content map, zijn er submappen die overeenkomen met de titels die u voor uw hoofdstukken hebt gekozen.

Als er bestanden of mappen zijn die u niet wilt publiceren, kunt u hun namen opnemen in het .vscodeignore bestand.

Laten we eens kijken jupyter-book.ts naar wat onze zojuist gevormde extensie doet.

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

De activate functie is de belangrijkste actie van uw extensie. Opdrachten die u wilt registreren, moeten worden weergegeven in de activate functie, vergelijkbaar met onze launchBook.test-book opdracht. In de processNotebooks functie vinden we onze extensiemap die ons Jupyter Book bevat en aanroept bookTreeView.openBook met behulp van de map van onze extensie als parameter.

Het package.json bestand speelt ook een belangrijke rol bij het registreren van de opdracht van onze extensie.

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

Met de activerings gebeurtenis activeert onCommandu de functie die we hebben geregistreerd bij het aanroepen van de opdracht. Er zijn enkele andere activeringsevenementen die mogelijk zijn voor aanvullende aanpassingen. Zie Activeringsevenementen voor meer informatie.

Uw extensie verpakken

Als u met anderen wilt delen, moet u de extensie in één bestand verpakken. Uw extensie kan worden gepubliceerd naar de Marketplace voor Azure Data Studio-extensies of worden gedeeld met uw team of community. Als u deze stap wilt uitvoeren, moet u een ander npm-pakket installeren vanaf de opdrachtregel.

npm install -g vsce

Bewerk het README.md bestand naar wens. Ga vervolgens naar de basismap van de extensie en voer deze uit vsce package. U kunt desgewenst een opslagplaats koppelen aan uw extensie of zonder de extensie doorgaan. Als u er een wilt toevoegen, voegt u een soortgelijke regel toe aan uw package.json bestand.

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

Nadat deze regels zijn toegevoegd, wordt er een my test-book-0.0.1.vsix bestand gemaakt en klaar voor installatie in Azure Data Studio.

Uw extensie uitvoeren

Als u uw extensie wilt uitvoeren en testen, opent u Azure Data Studio en opent u het opdrachtenpalet door Ctrl+Shift+P te selecteren. Zoek de opdrachtExtensies : Installeren vanuit VSIX en ga naar de map met de nieuwe extensie. Deze wordt nu weergegeven in uw extensievenster in Azure Data Studio.

Open het opdrachtpalet opnieuw en zoek de opdracht die we hebben geregistreerd, Start Book: Test Notebook. Bij het uitvoeren moet het Jupyter Book worden geopend dat we hebben verpakt met onze extensie.

Gefeliciteerd U hebt nu uw eerste Jupyter Book-extensie gebouwd en kunnen verzenden. Zie Boeken met Jupyter voor meer informatie over Jupyter Books.

Uw extensie publiceren naar Marketplace

De Marketplace voor Azure Data Studio-extensies is in aanbouw. Als u wilt publiceren, host u de extensie VSIX ergens, bijvoorbeeld op een GitHub-releasepagina. Dien een pull-aanvraag in waarmee dit JSON-bestand wordt bijgewerkt met uw extensiegegevens.

Volgende stappen

In deze zelfstudie heeft u het volgende geleerd:

• Maak een extensieproject.
• Installeer de extensiegenerator.
• Maak uw Jupyter Book-extensie.
• Pak uw extensie in.
• Publiceer uw extensie naar de marketplace.

We hopen dat u na het lezen van dit artikel ideeën hebt over Jupyter Books die u wilt delen met de Azure Data Studio-community.

Als u een idee hebt, maar niet zeker weet hoe u aan de slag kunt gaan, opent u een probleem of tweet u het team in azuredatastudio.

Voor meer informatie bevat de visual Studio Code-extensiegids alle bestaande API's en patronen.