Como documentar um Notebook com o Copilot no Fabric

Documentar um Notebook costuma ser a tarefa que fica sempre para o fim — e a primeira a ser esquecida. Ainda assim, é o que permite que outra pessoa, ou o nosso próprio "eu" de daqui a três meses, perceba o que o código faz e porquê. O Copilot no Microsoft Fabric resolve boa parte deste problema: consegue explicar o código célula a célula, em linguagem natural, e escrever a documentação em Markdown a partir do que já existe no Notebook. Vamos ver como fazer isto com um exemplo simples de PySpark.

Pré-requisitos

• Um workspace do Microsoft Fabric numa capacidade paga F2 ou superior (desde abril de 2025 o Copilot deixou de exigir capacidades grandes como F64).
• A definição de administrador "Users can use Copilot and other features powered by Azure OpenAI" ativada no tenant.
• Um Notebook do Fabric com, pelo menos, uma célula de código.
• Noções básicas de PySpark e de como executar células num Notebook.

Passo 1: Abrir o Copilot no Notebook

Abre o teu Notebook no Fabric. Na barra de ferramentas superior, clica no botão Copilot para abrir o painel de conversação (o chat pane) do lado direito do ecrã. É neste painel que vais escrever os pedidos e ler as respostas. Se o botão não aparecer, quase sempre é sinal de que a capacidade não é F2 ou superior, ou de que a definição de Copilot ainda não foi ativada — vale a pena confirmar com quem administra o tenant antes de avançar.

Passo 2: Preparar o código a documentar

Para o exemplo, vamos usar um caso pequeno e realista: ler uma tabela de vendas e calcular o total por região. Cola este código numa célula e executa-o, para que o Copilot tenha contexto sobre os dados e sobre o resultado que produzem.

from pyspark.sql.functions import sum

df = spark.read.table("vendas")
resumo = (df.groupBy("regiao")
            .agg(sum("valor").alias("total_vendas"))
            .orderBy("total_vendas", ascending=False))
display(resumo)

Repara que o código está limpo e com nomes claros. Isto não é por acaso: quanto mais legível estiver o código, mais precisa será a explicação que o Copilot consegue dar.

Passo 3: Pedir ao Copilot para explicar o código

No painel do Copilot, escreve um pedido simples e direto. Um bom exemplo é:

Explica, em português, o que faz cada célula deste notebook.

O Copilot lê o conteúdo das células e responde com uma explicação em linguagem natural: que tabela é lida, que agregação é feita e o que o resultado final representa. É a forma mais rápida de perceber um Notebook que herdaste de um colega ou que não tocas há meses. Se quiseres focar apenas uma parte, seleciona a célula e pede "explica só a célula selecionada" — o Copilot restringe a resposta a esse bloco.

Dica: quanto mais específico for o pedido ("explica o que representa a coluna valor"), mais útil é a resposta. Perguntas vagas geram respostas vagas.

Passo 4: Gerar e inserir a documentação em Markdown

Depois de perceberes o código, pede ao Copilot para transformar a explicação em documentação reutilizável:

Escreve documentação em Markdown para este notebook, com um título e uma secção por passo.

O resultado costuma ser parecido com isto:

## Resumo de vendas por região

Este notebook lê a tabela `vendas`, agrega o `valor` total
por `regiao` e apresenta o resultado ordenado do maior para
o menor total.

1. Importa a função de agregação `sum`.
2. Lê a tabela `vendas` para um DataFrame.
3. Agrupa por `regiao` e soma o `valor`.
4. Mostra o resumo com `display`.

Cria uma nova célula do tipo Markdown no topo do Notebook e cola lá o texto gerado. Revê sempre o que o Copilot escreveu: ele dá um excelente ponto de partida, mas o contexto de negócio — o que é a tabela "vendas", de onde vêm os dados, com que frequência são atualizados — só tu o conheces e deves acrescentá-lo.

Verificar o resultado

Para confirmar que ficou tudo bem, verifica três coisas. Primeiro, a célula Markdown deve aparecer formatada, com o título em destaque e a lista numerada legível. Segundo, a explicação tem de corresponder ao que o código faz de facto — lê com atenção, porque o Copilot pode enganar-se. Terceiro, e o mais importante: um colega que nunca viu o Notebook consegue perceber o objetivo só pela documentação? Se alguma frase estiver vaga ou incorreta, ajusta o pedido (por exemplo, "sê mais específico sobre a origem dos dados") e gera novamente.

Conclusão

Em poucos minutos passaste de um Notebook sem qualquer contexto para um Notebook explicado e documentado em Markdown, sem escreveres uma única linha de documentação à mão. Um próximo passo natural é pedir ao Copilot para comentar o próprio código ou para sugerir nomes de variáveis mais claros, tornando o Notebook ainda mais fácil de manter. E tu — qual vai ser o primeiro Notebook esquecido que finalmente vais documentar?