Publicação do Site de Documentação¶

Este guia descreve como provisionar a infraestrutura e configurar o pipeline de publicação automática do site MkDocs.

Visão geral¶

Push na branch master
    → Azure DevOps Pipeline (azure-pipelines.yml)
    → pip install requirements.txt
    → validate_release_notes.py
    → mkdocs build --strict
    → Azure Static Web Apps (hospedagem)

Pré-requisitos¶

• Acesso ao Azure Portal com permissão para criar recursos no grupo de recursos do AMia
• Acesso ao projeto Azure DevOps com permissão de administrador de pipeline
• Python 3.11 disponível no agente de build (ubuntu-latest inclui Python por padrão)

Passo 1 — Provisionar Azure Static Web Apps¶

Via Azure Portal¶

1. Acesse o Azure Portal
2. Crie um novo recurso: Static Web Apps
3. Configure:
4. Subscription: assinatura do AMia
5. Resource Group: grupo de recursos do AMia
6. Name: amia-roadmap-docs
7. Region: Brazil South
8. Plan: Free (suficiente para documentação)
9. Source: Other (o deploy será feito via pipeline Azure DevOps)
10. Clique em Review + Create → Create
11. Após criação, acesse o recurso e copie o Deployment Token

Via Terraform (recomendado para produção)¶

Adicione ao módulo Terraform existente:

resource "azurerm_static_web_app" "roadmap_docs" {
  name                = "amia-roadmap-docs"
  resource_group_name = azurerm_resource_group.amia.name
  location            = "Brazil South"
  sku_tier            = "Free"
  sku_size            = "Free"
}

Passo 2 — Configurar Variable Group no Azure DevOps¶

1. Acesse o projeto no Azure DevOps
2. Vá em Pipelines → Library → + Variable group
3. Configure:
4. Name: amia-roadmap-docs
5. Variables:
   • AZURE_STATIC_WEB_APPS_API_TOKEN = <deployment-token-do-passo-1>
   • Marque a variável como secret (cadeado)
6. Salve o Variable Group

Passo 3 — Criar o pipeline no Azure DevOps¶

1. Acesse Pipelines → New Pipeline
2. Selecione Azure Repos Git → repositório amIA-Roadmap
3. Selecione Existing Azure Pipelines YAML file
4. Caminho: /azure-pipelines.yml
5. Clique em Continue → Run

O pipeline executará imediatamente e publicará o site pela primeira vez.

Passo 4 — Verificar publicação¶

Após o pipeline concluir com sucesso:

1. Acesse o recurso Static Web Apps no Azure Portal
2. Copie a URL do site (ex: https://amia-roadmap-docs.azurestaticapps.net)
3. Acesse a URL e verifique que o site está funcionando

Configurar domínio customizado (opcional)¶

1. No recurso Static Web Apps, acesse Custom domains
2. Adicione o domínio desejado (ex: docs.amia.com)
3. Configure o registro DNS conforme instruído pelo Azure

Solução de problemas¶