Documentação
Como funciona o Antora?
Antora constrói este site de documentação a partir das configurações em um Antora Playbook, que é um arquivo YAML que descreve as fontes de documentação e a saída da compilação.
Fontes de conteúdo
Nosso playbook está armazenado na raiz do repositório principal do projeto Modern Gitops Stack, no antora -playbook.yml file. É este arquivo que define as fontes de conteúdo (no nosso caso cada módulo do projeto Modern Gitops Stack), bem como as tags a serem levadas em consideração na construção da documentação.
Neste arquivo você verá uma fonte para a documentação principal (ou seja, as páginas mais genéricas armazenadas no repositório principal) e fontes para cada módulo em uma lista em content.sources . Cada fonte é definida por um url para seu repositório e um start_path que informa ao Antora onde a respectiva documentação está armazenada.
Estrutura dos arquivos
Espera-se que cada fonte de documentação tenha uma estrutura de arquivo precisa, conforme documentado detalhadamente em documentação da Antora.
Resumindo, espera-se que a fonte de documentação tenha um arquivo antora.yml em sua raiz, uma pasta modules que contém os módulos de documentação e um nav.adoc. O arquivo nav.adoc é usado para gerar o menu de navegação à esquerda do site de documentação e as páginas de documentação são usadas para gerar o conteúdo do site. Você verá esta estrutura de pastas em todos os nossos módulos dentro da pasta docs.
Mais informações sobre o arquivo antora.yml e nav.adoc podem ser encontradas aqui e https:// docs.antora.org/antora/latest/navigation/files-and-lists/[aqui], respectivamente.
|
Resumindo, espera-se que nossas fontes de documentação tenham pelo menos a seguinte estrutura:
docs
├── antora.yml
└── modules
└── ROOT
├── nav.adoc
└── pages
└── ...
O antora.yml para cada módulo é bastante simples:
---
name: "<MODULE_NAME>" # O nome do módulo que aparecerá na URL da documentação gerada, use algo curto.
title: "<MODULE_NAME>" # O título do módulo que aparecerá no menu de navegação da documentação gerada.
version: true # Diz ao Antora para usar a tag de versão do módulo como a versão da documentação.
start_page: README.adoc # Informa ao Antora qual página usar como página inicial da documentação deste módulo.
nav:
- "modules/ROOT/nav.adoc" # Informa ao Antora qual arquivo de navegação usar para a documentação deste módulo.Versionamento
A página de documentação de cada módulo é versionada usando suas tags de repositório, que são criadas automaticamente pelo Release Please CI. Em cada fonte do nosso playbook Antora, podemos definir quais tags de versão incluímos ou excluímos usando a sintaxe explicada aqui.
No nosso caso, observe que optamos por usar as tags em vez das ramificações para versionar as páginas do documento. Isso ocorre porque lançamos cada nova versão em um único branch, mas por meio de várias tags. Mais explicações sobre os diferentes métodos de versionamento estão disponíveis aqui.
Construindo a documentação
Nossa documentação é construída usando uma ação GitHub no repositório principal, disponível em aqui.
No fluxo de trabalho, você notará que nossa documentação é gerada usando um imagem Docker personalizada do Antora. Isso ocorre porque precisamos de duas extensões no Antora, conforme explicado em README.adoc. O processo de liberação desta imagem também é explicado no referido README.adoc.
A UI das páginas de documentação vem de uma bifurcação da UI padrão do Antora, disponível aqui. Esta branch é usada para adicionar um realce de sintaxe personalizado para blocos de código Tofu/Terraform. Para usar esta UI, simplesmente criamos um pacote *.zip com um fluxo de trabalho GitHub Actions que é então apontado por nosso antora-playbook.yml.
O README.adoc do imagem personalizada do Docker contém um comando que você pode usar para construir as páginas de documentação localmente para visualizar suas alterações.
|
Depois de gerar a documentação, ela é publicada no branch gh-pages do repositório principal. Este branch é então usado pelo GitHub Pages para servir o site de documentação.
Documentação do módulo
A documentação de cada módulo é bastante particular no sentido de que não colocamos as páginas de documentação na pasta docs. Em vez disso, temos links simbólicos para README.adoc na raiz do repositório e para README.adoc dentro de cada variante. Consequentemente, um módulo típico tem uma estrutura como esta:
modern-gitops-stack-module-template
└── docs
├── antora.yml
└── modules
└── ROOT
├── nav.adoc
└── pages
├── aks
│ └── README.adoc -> ../../../../../aks/README.adoc
├── eks
│ └── README.adoc -> ../../../../../eks/README.adoc
├── kind
│ └── README.adoc -> ../../../../../kind/README.adoc
└── README.adoc -> ../../../../README.adoc
Como você pode ver, além da raiz README.adoc, cada variante deve ter seu próprio arquivo. Isso se deve à forma como a documentação automática é gerada (o Terraform Docs precisa colocar a documentação gerada em arquivos separados) e porque cada variante possui suas especificidades.
Um módulo simples sem variantes possui uma estrutura mais simples:
modern-gitops-stack-module-template
└── docs
├── antora.yml
└── modules
└── ROOT
├── nav.adoc
└── pages
└── README.adoc -> ../../../../README.adoc
Content
O module template contém um bom exemplo do que o README.adoc deve incluir em seu conteúdo.
Um bom README.adoc deve conter uma pequena descrição do que o módulo faz e, se instalar um gráfico, listar a versão do gráfico junto com um link para o gráfico oficial e documentação. A seguir, mostro alguns exemplos de utilização do módulo, do mais simples ao mais complexo. Por fim, o final do módulo conterá a documentação automática.
Um módulo que possui variantes será um pouco diferente. O README.adoc principal deve conter uma introdução e uma versão do gráfico, mas é o README.adoc de cada variante que deve ter exemplos de uso, pois estes são diferentes de variante para variante.
| Verifique as páginas de documentação do módulo existente para obter exemplos (o Thanos module é um bom exemplo de um módulo com variantes e o Keycloak module é um exemplo sem). |
Documentação do Terraform Docs
Você notará que as últimas seções do README.adoc que são geradas automaticamente pelo Terraform Docs.
Tudo o que está entre os comentários BEGIN_TF_DOCS / END_TF_DOCS e BEGIN_TF_TABLES / END_TF_TABLES é gerado automaticamente por um fluxo de trabalho GitHub, que está disponível no repositório principal.