Criar uma extensão Jupyter Book

Este tutorial demonstra como criar uma nova extensão do Jupyter Book Azure Data Studio. A extensão fornece um exemplo do Jupyter Book que pode ser aberto e executado no Azure Data Studio.

Neste artigo, vai aprender a:

• Crie um projeto de extensão.
• Instale o gerador de extensão.
• Crie sua extensão Jupyter Book.
• Execute sua extensão.
• Empacote sua extensão.
• Publique sua extensão no mercado.

APIs usadas

• bookTreeView.openBook

Casos de uso de extensão

Existem algumas razões diferentes pelas quais você criaria uma extensão Jupyter Book:

• Compartilhe documentação interativa organizada e seccionada
• Partilhar um livro completo (semelhante a um e-book, mas distribuído através do Azure Data Studio)
• Versão e acompanhe as atualizações do Jupyter Book

A principal diferença entre um Jupyter Book e uma extensão de notebook é que um Jupyter Book fornece organização. Dezenas de cadernos podem ser divididos em diferentes capítulos em um Jupyter Book, mas a extensão do notebook destina-se a enviar um pequeno número de cadernos individuais.

Pré-requisitos

O Azure Data Studio é criado na mesma estrutura do Visual Studio Code, portanto, as extensões para o Azure Data Studio são criadas usando o Visual Studio Code. Para começar, você precisa dos seguintes componentes:

• Node.js instalado e disponível no seu $PATH. Node.js inclui o npm, o Node.js Package Manager, que é usado para instalar o gerador de extensão.
• Visual Studio Code para fazer quaisquer alterações em sua extensão e depurar a extensão.
• Certifique-se de azuredatastudio que está no seu caminho. Para Windows, certifique-se de escolher a opção Adicionar ao caminho no setup.exe. Para Mac ou Linux, execute o comando Instalar 'azuredatastudio' no PATH a partir da Paleta de Comandos no Azure Data Studio.

Instale o gerador de extensões

Para simplificar o processo de criação de extensões, construímos um gerador de extensões usando o Yeoman. Para instalá-lo, execute o seguinte comando no prompt de comando:

npm install -g yo generator-azuredatastudio

Crie a sua extensão

Para criar uma extensão:

1. Inicie o gerador de extensões com o seguinte comando:

   yo azuredatastudio

2. Escolha New Jupyter Book na lista de tipos de extensão.

   

3. Siga as etapas para preencher o nome da extensão. Para este tutorial, use o Livro de Teste. Em seguida, preencha um nome de editor. Para este tutorial, use a Microsoft. Finalmente, adicione uma descrição.

Você opta por fornecer um Livro Jupyter existente, usar um livro de amostra fornecido ou trabalhar para criar um novo Livro Jupyter. Todas as três opções são mostradas.

Fornecer um livro existente

Se você quiser enviar um livro que já criou, forneça o caminho absoluto do arquivo para a pasta onde o conteúdo do livro vive. Você pode então estar pronto para aprender sobre a extensão e enviá-la.

Use o livro de exemplo

Se você não tiver um livro ou cadernos existentes, poderá usar a amostra fornecida no gerador.

O livro de exemplo demonstra como é um simples Jupyter Book. Se você quiser saber mais sobre como personalizar um Jupyter Book, consulte a seção a seguir sobre como criar um novo livro com blocos de anotações existentes.

Criar um novo livro

Se você tiver cadernos que deseja empacotar em um Jupyter Book, você pode. O gerador pergunta se você quer capítulos em seu livro e, em caso afirmativo, quantos e seus títulos. Pode ver como é o processo de seleção aqui. Use a Barra de espaço para selecionar quais blocos de anotações você deseja colocar em cada capítulo.

Concluir as etapas anteriores cria uma nova pasta com seu novo Jupyter Book. Abra a pasta no Visual Studio Code e você estará pronto para enviar sua extensão Jupyter Book.

Entenda sua extensão

Este é o aspeto que o seu projeto deve ter atualmente:

O vsc-extension-quickstart.md arquivo fornece uma referência dos arquivos importantes. O README.md arquivo é onde você pode fornecer documentação para sua nova extensão. Observe os package.jsonarquivos , jupyter-book.ts, content, e toc.yml . A content pasta contém todos os arquivos de bloco de anotações ou markdown. O toc.yml estrutura seu Jupyter Book e é gerado automaticamente se você optou por criar um Jupyter Book personalizado através do gerador de extensão.

Se você criou um livro usando o gerador e optou por capítulos em seu livro, sua estrutura de pastas ficaria um pouco diferente. Em vez de seus arquivos de marcação e Jupyter Notebook vivendo na content pasta, haveria subpastas que correspondem aos títulos que você escolheu para seus capítulos.

Se houver algum arquivo ou pasta que você não deseja publicar, você pode incluir seus nomes no .vscodeignore arquivo.

Vamos dar uma olhada para jupyter-book.ts entender o que nossa extensão recém-formada está fazendo.

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

A activate função é a ação principal da sua extensão. Todos os comandos que você deseja registrar devem aparecer dentro da activate função, semelhante ao nosso launchBook.test-book comando. Dentro da função, encontramos nossa processNotebooks pasta de extensão que contém nosso Livro Jupyter e chamada bookTreeView.openBook usando a pasta de nossa extensão como parâmetro.

O package.json arquivo também desempenha um papel importante no registro do comando da nossa extensão.

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

O evento de ativação, onCommand, dispara a função que registramos quando invocamos o comando. Existem alguns outros eventos de ativação que são possíveis para personalização adicional. Para obter mais informações, consulte Eventos de ativação.

Empacote sua extensão

Para compartilhar com outras pessoas, você precisa empacotar a extensão em um único arquivo. Sua extensão pode ser publicada no mercado de extensões do Azure Data Studio ou compartilhada com sua equipe ou comunidade. Para fazer essa etapa, você precisa instalar outro pacote npm a partir da linha de comando.

npm install -g vsce

Edite o README.md ficheiro ao seu gosto. Em seguida, vá para o diretório base da extensão e execute vsce package. Opcionalmente, você pode vincular um repositório à sua extensão ou continuar sem um. Para adicionar uma, adicione uma linha semelhante ao seu package.json ficheiro.

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

Depois que essas linhas são adicionadas, um my test-book-0.0.1.vsix arquivo é criado e pronto para instalação no Azure Data Studio.

Execute sua extensão

Para executar e testar sua extensão, abra o Azure Data Studio e abra a paleta de comandos selecionando Ctrl+Shift+P. Encontre o comando Extensões: Instalar a partir do VSIX e vá para a pasta que contém a nova extensão. Agora ele deve aparecer no seu painel de extensão no Azure Data Studio.

Abra a paleta de comandos novamente e localize o comando que registramos, Launch Book: Test Notebook. Ao correr, ele deve abrir o Jupyter Book que empacotamos com nossa extensão.

Parabéns! Você construiu e agora pode enviar sua primeira extensão Jupyter Book. Para obter mais informações sobre o Jupyter Books, consulte Livros com o Jupyter.

Publique sua extensão no Marketplace

O mercado de extensão do Azure Data Studio está em construção. Para publicar, hospede a extensão VSIX em algum lugar, por exemplo, em uma página de versão do GitHub. Envie uma solicitação pull que atualize esse arquivo JSON com suas informações de extensão.

Próximos passos

Neste tutorial, ficou a saber como:

• Crie um projeto de extensão.
• Instale o gerador de extensão.
• Crie sua extensão Jupyter Book.
• Empacote sua extensão.
• Publique sua extensão no mercado.

Esperamos que, depois de ler este artigo, você tenha ideias sobre o Jupyter Books que gostaria de compartilhar com a comunidade do Azure Data Studio.

Se você tiver uma ideia, mas não tiver certeza de como começar, abra um problema ou tweete a equipe do azuredatastudio.

Para obter mais informações, o guia de extensão de código do Visual Studio abrange todas as APIs e padrões existentes.