Creare un'estensione Jupyter Book

Importante

Azure Data Studio ritira il 28 febbraio 2026. È consigliabile usare l'estensione MSSQL per Visual Studio Code. Per altre informazioni sulla migrazione a Visual Studio Code, vedere Che cosa accade in Azure Data Studio?

Questa esercitazione dimostra come creare un'estensione di Jupyter Book per Azure Data Studio. L'estensione fornisce un book Jupyter di esempio che può essere aperto ed eseguito in Azure Data Studio.

In questo articolo viene spiegato come:

• Creare un progetto di estensione.
• Installare il generatore di estensioni.
• Crea l'estensione Jupyter Libro.
• Esegui la tua estensione.
• Creare il pacchetto dell'estensione.
• Pubblicare l'estensione nel marketplace.

Le API utilizzate

• bookTreeView.openBook

Casi d'uso dell'estensione

Ci sono diversi motivi per cui potresti creare un'estensione Jupyter Book:

• Condividere documentazione interattiva organizzata e suddivisa in sezioni
• Condividere un book completo (simile a un e-book ma distribuito tramite Azure Data Studio)
• Versionare e tenere traccia degli aggiornamenti del libro Jupyter

La differenza principale tra un Jupyter Book e un'estensione di notebook è che un Jupyter Book ti offre una organizzazione migliore. Dozzine di notebook possono essere suddivisi in capitoli diversi in un Jupyter Book, ma l'estensione per notebook è destinata a distribuire un numero ridotto di singoli notebook.

Prerequisiti

Azure Data Studio si basa sullo stesso framework di Visual Studio Code, quindi le estensioni per Azure Data Studio vengono compilate usando Visual Studio Code. Per iniziare, sono necessari i componenti seguenti:

• Node.js installato e disponibile in $PATH. Node.js include npm, lo strumento di gestione dei pacchetti di Node.js, che viene usato per installare il generatore di estensioni.
• Visual Studio Code per apportare modifiche all'estensione ed eseguire il debug dell'estensione.
• Assicurati che azuredatastudio sia nel percorso. Per Windows, assicurarsi di scegliere l'opzione Aggiungi a PATH in setup.exe. Per Mac o Linux, eseguire il comando Install 'azuredatastudio' in PATH dal riquadro comandi in Azure Data Studio.

Installare il generatore di estensioni

Per semplificare il processo di creazione delle estensioni, abbiamo creato un generatore di estensioni con Yeoman. Per installarlo, eseguire il comando seguente dal prompt dei comandi:

npm install -g yo generator-azuredatastudio

Creare l'estensione

Per creare un'estensione:

1. Avviare il generatore di estensioni con il comando seguente:

   yo azuredatastudio

2. Scegliere Nuovo libro Jupyter nell'elenco dei tipi di estensione.

   

3. Seguire la procedura per specificare il nome dell'estensione. Per questa esercitazione usare Test Book. Immettere quindi un nome di editore. Per questa esercitazione usare Microsoft. Infine aggiungere una descrizione.

È possibile scegliere di fornire un libro Jupyter esistente, utilizzare un libro di esempio fornito o lavorare per creare un nuovo libro Jupyter. Tutte e tre le opzioni sono visualizzate.

Fornire un libro esistente

Se si vuole distribuire un book già creato, specificare il percorso di file assoluto della cartella in cui si trova il contenuto del book. Sarai quindi pronto a proseguire scoprendo di più sull'estensione e sulla sua distribuzione.

Usare il libro di esempio

Se non hai libri o quaderni già esistenti, puoi utilizzare l'esempio fornito dal generatore.

Il libro di esempio dimostra l'aspetto di un semplice libro Jupyter. Per informazioni sulla personalizzazione di un book Jupyter, vedere la sezione seguente che descrive come creare un nuovo book con notebook esistenti.

Creare un nuovo libro

È possibile raccogliere in un book Jupyter eventuali notebook esistenti. Il generatore chiede se si desiderano capitoli nel libro e, in caso affermativo, quanti e quali. Il processo di selezione è illustrato di seguito. Usare la barra spaziatrice per selezionare i notebook da inserire in ogni capitolo.

Il completamento dei passaggi precedenti consente di creare una nuova cartella con il nuovo book Jupyter. Apri la cartella in Visual Studio Code e sei pronto per distribuire la tua estensione Jupyter Book.

Comprendi la tua estensione

Il progetto dovrebbe essere simile al seguente:

Il file vsc-extension-quickstart.md fornisce informazioni di riferimento sui file importanti. Il file README.md è la posizione in cui è possibile fornire la documentazione per la nuova estensione. Si notino i file package.json, jupyter-book.ts, content e toc.yml. Nella cartella content si trovano tutti i notebook o i file markdown. Il file toc.yml definisce la struttura del book Jupyter e viene generato automaticamente se si è scelto di creare un book Jupyter personalizzato tramite il generatore di estensioni.

Se è stato creato un book usando il generatore e si è scelto di usare i capitoli nel book, la struttura di cartelle avrà un aspetto leggermente diverso. Invece dei file markdown e di Jupyter Notebook nella cartella content, saranno presenti sottocartelle corrispondenti ai titoli scelti per i capitoli.

Se sono presenti file o cartelle che non si vuole pubblicare, è possibile includere i relativi nomi nel file .vscodeignore.

Verrà ora esaminato il file jupyter-book.ts per comprendere le funzioni dell'estensione appena creata.

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

La funzione activate è l'azione principale dell'estensione. Tutti i comandi da registrare devono essere specificati all'interno della funzione activate, in modo analogo al comando launchBook.test-book. All'interno della funzione processNotebooks è possibile trovare la cartella dell'estensione che contiene il book Jupyter e chiamare bookTreeView.openBook usando la cartella dell'estensione come parametro.

Anche il file package.json ha un ruolo importante per la registrazione del comando dell'estensione.

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

L'evento di attivazione onCommand attiva la funzione registrata quando si richiama il comando. Esistono alcuni altri eventi di attivazione possibili per personalizzazioni aggiuntive. Per altre informazioni, vedere Eventi di attivazione.

Creare il pacchetto dell'estensione

Per condividere l'estensione con altri utenti, è necessario inserirla in un pacchetto costituito da un unico file. L'estensione può essere pubblicata nel marketplace delle estensioni di Azure Data Studio o condivisa all'interno del team o della community. A tale scopo, è necessario installare un altro pacchetto npm dalla riga di comando.

npm install -g vsce

Modificare il file README.md nel modo desiderato. Passare quindi alla directory di base dell'estensione ed eseguire vsce package. Facoltativamente, è possibile collegare un repository con l'estensione o continuare senza. Per aggiungerne uno, aggiungere una riga simile al file package.json.

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

Dopo aver aggiunto queste righe, viene creato un file my test-book-0.0.1.vsix e si è pronti per l'installazione in Azure Data Studio.

Eseguire l'estensione

Per eseguire e testare l'estensione, aprire Azure Data Studio e aprire il riquadro comandi selezionando CTRL+MAIUSC+P. Trovare il comando Estensioni: Installa da VSIX e passare alla cartella che contiene la nuova estensione. L'estensione dovrebbe ora comparire nel pannello delle estensioni in Azure Data Studio.

Apri di nuovo la palette dei comandi e trova il comando registrato Lancia libro: notebook di test. Una volta eseguito, dovrebbe aprire il Jupyter Book che abbiamo confezionato con la nostra estensione.

Complimenti. È stata creata la prima estensione di tipo book Jupyter ed è ora possibile distribuirla. Per ulteriori informazioni sui libri Jupyter, vedere Libri con Jupyter.

Pubblicare l'estensione nel marketplace

Il marketplace delle estensioni di Azure Data Studio è in costruzione. Per pubblicare, ospitare l'estensione VSIX in una posizione qualsiasi, ad esempio, in una pagina di rilascio di GitHub. Inviare una richiesta pull che aggiorna questo file JSON con le informazioni sull'estensione.

Passaggi successivi

In questa esercitazione, hai imparato come:

• Creare un progetto di estensione.
• Installare il generatore di estensioni.
• Crea l'estensione Jupyter Libro.
• Creare il pacchetto dell'estensione.
• Pubblicare l'estensione nel marketplace.

Ci auguriamo che, dopo aver letto questo articolo, avrete delle idee sui Jupyter Books che vorreste condividere con la comunità di Azure Data Studio.

Se si ha un'idea, ma non si è certi di come iniziare, aprire un problema o inviare un tweet al team: azuredatastudio.

Per altre informazioni, vedere la Guida delle estensioni di Visual Studio Code che documenta tutte le API e i modelli esistenti.