Go, AST e Antora: Documentação Específica para Aplicações Go

No dinâmico mundo do desenvolvimento web, a documentação desempenha um papel crucial na colaboração entre equipes, na manutenção do código e na garantia de que os engenheiros possam entender, configurar e operar as aplicações corretamente. No entanto, manter a documentação atualizada, especialmente em projetos complexos, pode ser um desafio significativo. Este artigo explora uma abordagem inovadora para gerar documentação específica para aplicações Go, utilizando a biblioteca AST (Abstract Syntax Tree) do Go e a ferramenta Antora, um gerador de sites estáticos.

O Desafio da Documentação em Projetos Go

Em projetos complexos, como o gerenciamento de pipelines de tarefas no Kubernetes, a necessidade de documentação clara e atualizada é ainda mais crítica. Imagine uma situação em que engenheiros de diferentes equipes contribuem com tarefas na forma de arquivos Go, e outros engenheiros precisam entender como configurar, depurar e operar essas tarefas. A documentação desatualizada pode levar a erros, atrasos e frustração.

As ferramentas tradicionais de documentação, como GoDoc, JavaDoc ou Python Docstrings, oferecem funcionalidades básicas para gerar documentação a partir de comentários no código. No entanto, essas ferramentas geralmente geram conteúdo muito acoplado ao ecossistema da linguagem e com customização limitada. O foco principal é documentar a API para outros desenvolvedores, e não o comportamento da aplicação em si.

A chave para uma documentação eficaz é mantê-la o mais próximo possível do código-fonte. No entanto, quando a documentação é mantida em um local separado, como um runbook, ela pode rapidamente se tornar desatualizada à medida que o código evolui. A solução ideal é gerar a documentação diretamente do código-fonte, garantindo que ela esteja sempre sincronizada com a implementação.

Go AST e Antora: Uma Solução Personalizada

Este artigo apresenta uma solução que combina o poder do Go AST com a flexibilidade do Antora para gerar documentação específica para aplicações Go. O Go AST permite analisar o código-fonte Go e extrair informações relevantes, como tipos, funções e comentários. O Antora, por sua vez, é um gerador de sites estáticos que permite criar documentação abrangente a partir de diversas fontes, incluindo arquivos Markdown ou AsciiDoc.

A abordagem descrita neste artigo envolve os seguintes passos:

• Geração de arquivos Markdown: Para cada tipo de tarefa, um arquivo Markdown é gerado, descrevendo a lógica da tarefa e as etapas envolvidas.
• Conversão para AsciiDoc (opcional): Os arquivos Markdown podem ser convertidos para AsciiDoc para melhor integração com o Antora.
• Integração com Antora: Os arquivos AsciiDoc são integrados aos recursos do Antora, e o site é construído.

Implementando a Geração de Documentação

Para implementar a geração de documentação, o artigo utiliza a ferramenta Mage como um sistema de build. A estrutura de diretórios é organizada da seguinte forma:

.
├── magefile.go
└── mage
    └── docs
        ├── lib.go
        └── task_docs.go

O arquivo magefile.go contém a função que dispara a geração da documentação:

// magefile.go
func Docs(outputDir string) error {
    return docs.GenerateDocs(outputDir)
}

Para implementar a função GenerateDocs, é necessário definir tipos que representem a documentação, como TypeIdent, TaskDocs e StepDoc. Esses tipos armazenam informações sobre a lógica das tarefas, as etapas envolvidas e a documentação associada.

A função GenerateDocs extrai a documentação das tarefas e etapas dos comentários no código-fonte, gera os arquivos Markdown e os escreve no diretório de saída. A função ExtractTaskAndStepDocs é responsável por percorrer os arquivos .go no projeto e extrair a documentação dos comentários, utilizando o Go AST.

Analisando o Código com Go AST

A função processFile utiliza o Go AST para analisar os arquivos Go e extrair a documentação dos comentários. A função ast.Inspect é usada para percorrer a AST e encontrar todas as declarações de tipo. Cada declaração é processada na função processDeclaration.

A função processDeclaration verifica se o tipo é uma struct e se é uma lógica de tarefa ou uma etapa. Se for uma lógica de tarefa, ela é processada na função processTaskLogic. Se for uma etapa, ela é processada na função processTaskStep. Essas funções extraem a documentação dos comentários e a armazenam nas estruturas de dados apropriadas.

Gerando os Arquivos Markdown

Após extrair a documentação, a função GenerateMarkdownDocs gera os arquivos Markdown. Cada tarefa recebe seu próprio arquivo Markdown, que descreve a lógica da tarefa, as etapas envolvidas e a documentação associada. A função WriteMarkdownDocsToFiles escreve os arquivos Markdown no diretório de saída.

Integrando com Antora

Para integrar a documentação gerada com Antora, é possível converter os arquivos Markdown para AsciiDoc utilizando a ferramenta Pandoc. Um script Bash pode ser utilizado para automatizar essa conversão e gerar um arquivo de navegação para o Antora.

#!/bin/bash
# integrate_go_docs.sh

if [ "$#" -ne 2 ]; then
  echo "Usage: $0 <md_dir> <pages_dir>"
  exit 1
fi

if ! command -v pandoc &> /dev/null
then
  echo "Error: pandoc is not installed. Please install pandoc to continue."
  exit 1
fi

md_dir=$1
pages_dir=$2

tasks_dir="components/operator/tasks"
nav_file="$pages_dir/../partials/task-operator-nav.adoc"

echo "// This file has been generated on $(date)" > "$nav_file"

# Convert task docs
for md_file in "$md_dir"/*.md
do
  adoc_dir="$pages_dir/$tasks_dir"
  adoc_file=$(basename "${md_file%.md}.adoc")
  adoc_path="$adoc_dir/$adoc_file"
  echo "Integrating $md_file"
  # -s to create a standalone document, including the title (=)
  # --shift-heading-level-by -1 to convert the markdown h1 (#) to asciidoc title (=)
  # See https://github.com/jgm/pandoc/issues/5615
  #
  # --wrap=none to avoid wrapping lines, causing long headlines to be broken
  # See https://github.com/jgm/pandoc/issues/3277#issuecomment-264706794
  pandoc -s -f markdown --shift-heading-level-by "-1" --wrap=none -t asciidoc -o "$adoc_path" "$md_file"
  echo "* xref:$tasks_dir/$adoc_file[]" >> "$nav_file"
done

Com os arquivos AsciiDoc e o arquivo de navegação em seus devidos lugares, o site Antora pode ser construído.

Automação com GitHub Actions

Para automatizar o processo de geração e integração da documentação, é possível utilizar o GitHub Actions. O workflow do GitHub Actions executa as seguintes etapas:

1. Faz o checkout do código-fonte.
2. Configura o ambiente Go.
3. Instala as dependências.
4. Gera a documentação.
5. Converte os arquivos Markdown para AsciiDoc.
6. Constrói o site Antora.
7. Publica o site.

Conclusão

A geração de documentação a partir do código-fonte é uma prática essencial para garantir a qualidade e a manutenibilidade de projetos Go. A combinação do Go AST com o Antora oferece uma solução flexível e poderosa para gerar documentação específica para aplicações, focada no comportamento da aplicação e adaptada às necessidades de cada projeto. Esta abordagem não apenas simplifica a tarefa de manter a documentação atualizada, mas também promove uma melhor colaboração entre as equipes e um entendimento mais profundo do código.

No futuro, podemos esperar ver ainda mais ferramentas e técnicas que facilitam a geração de documentação a partir do código-fonte, com foco em inteligência artificial e aprendizado de máquina para automatizar a extração de informações relevantes e a criação de documentação de alta qualidade. A capacidade de gerar documentação automaticamente será cada vez mais importante para lidar com a crescente complexidade dos projetos de software e garantir o sucesso a longo prazo.