Membuat ekstensi Jupyter Book

Tutorial ini menunjukkan cara membuat ekstensi Jupyter Book Azure Data Studio baru. Ekstensi mengirimkan sampel Jupyter Book yang dapat dibuka dan dijalankan di Azure Data Studio.

Di artikel ini, Anda akan mempelajari cara:

• Membuat proyek ekstensi.
• Pasang generator ekstensi.
• Buat ekstensi Jupyter Book Anda.
• Jalankan ekstensi Anda.
• Kemas ekstensi Anda.
• Terbitkan ekstensi Anda ke marketplace.

API yang digunakan

• bookTreeView.openBook

Kasus penggunaan ekstensi

Ada beberapa alasan berbeda mengapa Anda akan membuat ekstensi Jupyter Book:

• Berbagi dokumentasi interaktif terorganisir dan terbagi
• Berbagi buku lengkap (mirip dengan e-book tetapi didistribusikan melalui Azure Data Studio)
• Versi dan melacak pembaruan Jupyter Book

Perbedaan utama antara Jupyter Book dan ekstensi notebook adalah bahwa Jupyter Book memberi Anda organisasi. Puluhan buku catatan dapat dibagi menjadi bab yang berbeda dalam Buku Jupyter, tetapi ekstensi notebook dimaksudkan untuk mengirim sejumlah kecil buku catatan individual.

Prasyarat

Azure Data Studio dibangun pada kerangka kerja yang sama dengan Visual Studio Code, sehingga ekstensi untuk Azure Data Studio dibuat dengan menggunakan Visual Studio Code. Untuk memulai, Anda memerlukan komponen berikut:

• Node.js terinstal dan tersedia di .$PATH Node.js mencakup npm, Node.js Package Manager, yang digunakan untuk menginstal generator ekstensi.
• Visual Studio Code untuk membuat perubahan apa pun pada ekstensi Anda dan men-debug ekstensi.
• Pastikan azuredatastudio berada di jalur Anda. Untuk Windows, pastikan Anda memilih opsi Tambahkan ke Jalur di setup.exe. Untuk Mac atau Linux, jalankan perintah Instal 'azuredatastudio' di PATH dari Palet Perintah di Azure Data Studio.

Menginstal generator ekstensi

Untuk menyederhanakan proses pembuatan ekstensi, kami telah membangun generator ekstensi menggunakan Yeoman. Untuk menginstalnya, jalankan perintah berikut dari prompt perintah:

npm install -g yo generator-azuredatastudio

Membuat ekstensi Anda

Untuk membuat ekstensi:

1. Mulai generator ekstensi dengan perintah berikut:

   yo azuredatastudio

2. Pilih Buku Jupyter Baru dari daftar jenis ekstensi.

   

3. Ikuti langkah-langkah untuk mengisi nama ekstensi. Untuk tutorial ini, gunakan Test Book. Kemudian isi nama penerbit. Untuk tutorial ini, gunakan Microsoft. Terakhir, tambahkan deskripsi.

Anda memilih untuk menyediakan Jupyter Book yang ada, menggunakan buku sampel yang disediakan, atau bekerja untuk membuat Jupyter Book baru. Ketiga opsi ditampilkan.

Menyediakan buku yang sudah ada

Jika Anda ingin mengirim buku yang telah Anda buat, berikan jalur file absolut ke folder tempat konten buku Anda berada. Anda kemudian dapat siap untuk melanjutkan untuk mempelajari ekstensi dan mengirimkannya.

Menggunakan buku sampel

Jika Anda tidak memiliki buku atau buku catatan yang sudah ada, Anda bisa menggunakan sampel yang disediakan di generator.

Contoh buku menunjukkan seperti apa Jupyter Book sederhana. Jika Anda ingin mempelajari tentang mengkustomisasi Jupyter Book, lihat bagian berikut ini tentang cara membuat buku baru dengan buku catatan yang sudah ada.

Membuat buku baru

Jika Anda memiliki buku catatan yang ingin Anda kemas ke dalam Jupyter Book, Anda bisa. Generator bertanya apakah Anda ingin bab dalam buku Anda, dan jika demikian, berapa banyak dan judulnya. Anda dapat melihat seperti apa proses pemilihan di sini. Gunakan Bilah Spasi untuk memilih buku catatan mana yang ingin Anda tempatkan di setiap bab.

Menyelesaikan langkah-langkah sebelumnya membuat folder baru dengan Jupyter Book baru Anda. Buka folder di Visual Studio Code, dan Anda siap untuk mengirim ekstensi Jupyter Book Anda.

Memahami ekstensi Anda

Seperti inilah proyek Anda saat ini harus terlihat:

File ini vsc-extension-quickstart.md memberi Anda referensi file penting. File README.md adalah tempat Anda dapat menyediakan dokumentasi untuk ekstensi baru Anda. package.jsonPerhatikan file , jupyter-book.ts, content, dan toc.yml . Folder content menyimpan semua file buku catatan atau markdown. Struktur toc.yml Jupyter Book Anda dan dibuat secara otomatis jika Anda memilih untuk membuat Jupyter Book kustom melalui generator ekstensi.

Jika Anda membuat buku dengan menggunakan generator dan memilih bab dalam buku Anda, struktur folder Anda akan terlihat sedikit berbeda. Alih-alih file markdown dan Jupyter Notebook Anda yang tinggal di content folder, akan ada subfolder yang sesuai dengan judul yang Anda pilih untuk bab Anda.

Jika ada file atau folder yang tidak ingin Anda terbitkan, Anda dapat menyertakan namanya dalam .vscodeignore file.

Mari kita lihat jupyter-book.ts untuk memahami apa yang sedang dilakukan ekstensi yang baru dibentuk.

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

Fungsi ini activate adalah tindakan utama ekstensi Anda. Perintah apa pun yang ingin Anda daftarkan akan muncul di activate dalam fungsi, mirip dengan perintah kami launchBook.test-book . processNotebooks Di dalam fungsi, kami menemukan folder ekstensi kami yang menyimpan Jupyter Book dan memanggil bookTreeView.openBook dengan menggunakan folder ekstensi kami sebagai parameter.

File ini package.json juga memainkan peran penting dalam mendaftarkan perintah ekstensi kami.

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

Peristiwa aktivasi, onCommand, memicu fungsi yang kami daftarkan ketika kami memanggil perintah . Ada beberapa peristiwa aktivasi lain yang dimungkinkan untuk penyesuaian tambahan. Untuk informasi selengkapnya, lihat Peristiwa aktivasi.

Mengemas ekstensi Anda

Untuk berbagi dengan orang lain, Anda perlu mengemas ekstensi ke dalam satu file. Ekstensi Anda dapat diterbitkan ke marketplace ekstensi Azure Data Studio atau dibagikan dengan tim atau komunitas Anda. Untuk melakukan langkah ini, Anda perlu menginstal paket npm lain dari baris perintah.

npm install -g vsce

README.md Edit file sesuai keinginan Anda. Kemudian buka direktori dasar ekstensi, dan jalankan vsce package. Anda dapat secara opsional menautkan repositori dengan ekstensi Anda atau melanjutkan tanpa repositori. Untuk menambahkannya, tambahkan baris serupa ke file Anda package.json .

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

Setelah baris ini ditambahkan, my test-book-0.0.1.vsix file dibuat dan siap diinstal di Azure Data Studio.

Jalankan ekstensi Anda

Untuk menjalankan dan menguji ekstensi Anda, buka Azure Data Studio dan buka palet perintah dengan memilih Ctrl+Shift+P. Temukan perintah Ekstensi: Instal dari VSIX, dan buka folder yang berisi ekstensi baru Anda. Sekarang akan muncul di panel ekstensi Anda di Azure Data Studio.

Buka palet perintah lagi, dan temukan perintah yang kami daftarkan, Luncurkan Buku: Uji Buku Catatan. Setelah berjalan, itu harus membuka Jupyter Book yang kami kemas dengan ekstensi kami.

Selamat! Anda membangun dan sekarang dapat mengirim ekstensi Jupyter Book pertama Anda. Untuk informasi selengkapnya tentang Jupyter Books, lihat Buku dengan Jupyter.

Menerbitkan ekstensi Anda ke Marketplace

Marketplace ekstensi Azure Data Studio sedang dibangun. Untuk menerbitkan, host ekstensi VSIX di suatu tempat, misalnya, pada halaman rilis GitHub. Kirim permintaan pull yang memperbarui file JSON ini dengan informasi ekstensi Anda.

Langkah berikutnya

Dalam tutorial ini, Anda mempelajari cara:

• Membuat proyek ekstensi.
• Pasang generator ekstensi.
• Buat ekstensi Jupyter Book Anda.
• Kemas ekstensi Anda.
• Terbitkan ekstensi Anda ke marketplace.

Kami berharap setelah membaca artikel ini, Anda akan memiliki ide tentang Jupyter Books yang ingin Anda bagikan dengan komunitas Azure Data Studio.

Jika Anda memiliki ide tetapi tidak yakin cara memulai, buka masalah atau tweet tim di azuredatastudio.

Untuk informasi selengkapnya, panduan ekstensi Visual Studio Code mencakup semua API dan pola yang ada.