Creare un'estensione di tipo book Jupyter

Questa esercitazione illustra come creare una nuova estensione di Azure Data Studio di tipo book Jupyter. 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.
• Creare l'estensione di tipo book Jupyter.
• Eseguire l'estensione.
• Creare il pacchetto dell'estensione.
• Pubblicare l'estensione nel marketplace.

API usate

• bookTreeView.openBook

Casi d'uso dell'estensione

Esistono diversi motivi per cui può essere utile creare un'estensione di tipo book Jupyter:

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

La differenza principale tra un'estensione di tipo book Jupyter e di tipo notebook è che un book Jupyter supporta l'organizzazione. Decine di notebook possono essere suddivisi in capitoli diversi in un book Jupyter, ma l'estensione di tipo notebook è progettata per 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.
• Assicurarsi 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 New book Jupyter (Nuovo book 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 autore. Per questa esercitazione usare Microsoft. Infine aggiungere una descrizione.

È possibile scegliere di specificare un book Jupyter esistente, usare un book di esempio specificato o creare un nuovo book Jupyter. Tutte e tre le opzioni sono visualizzate.

Specificare un book 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. Sarà quindi possibile procedere per scoprire di più sull'estensione e la distribuzione.

Usare il book di esempio

Se non sono già disponibili book o notebook esistenti, è possibile usare l'esempio fornito nel generatore.

Il book di esempio dimostra l'aspetto di un semplice book 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 book

È possibile raccogliere in un book Jupyter eventuali notebook esistenti. Il generatore chiede se si vogliono creare capitoli nel book e, in caso affermativo, il numero e i titoli. 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. Aprire la cartella in Visual Studio Code e si è pronti per distribuire l'estensione book Jupyter.

Informazioni sull'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. La cartella content include 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: installare da VSIX e passare alla cartella che contiene la nuova estensione. L'estensione dovrebbe ora comparire nel pannello delle estensioni in Azure Data Studio.

Aprire di nuovo il riquadro comandi e trovare il comando registrato, Launch Book: Test Notebook. Eseguendo questo comando verrà aperto il book Jupyter per il quale è stato creato un pacchetto con l'estensione.

Congratulazioni. È stata creata la prima estensione di tipo book Jupyter ed è ora possibile distribuirla. Per altre informazioni sui book Jupyter, vedere Books with Jupyter (Book 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

Questa esercitazione ha descritto come:

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

Dopo aver completato la lettura di questo articolo, è possibile dare spazio alle proprie idee e condividere nuovi book Jupyter con la community 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.