Publicar a documentação de uma aplicação¶

Cada aplicação builda e publica a própria documentação; o site central (docs.xadm.biz) só agrega e serve. O contrato entre as partes é um bucket no Garage:

flowchart LR
    A[Repo do app] -- "CI: mkdocs build<br/>+ javadoc/dartdoc" --> S[(Garage<br/>docs-sites/&lt;app&gt;/)]
    S -- "sync a cada ~90s" --> C[docs.xadm.biz<br/>/aplicacoes/&lt;app&gt;/]

O contrato¶

O app publica um site estático completo no bucket docs-sites, no prefixo com o nome do app: docs-sites/<app>/ (precisa ter index.html na raiz do prefixo).
O site central sincroniza o bucket a cada ~90s e serve cada prefixo em https://docs.xadm.biz/aplicacoes/<app>/. App novo = publicar no bucket — nenhuma configuração no repo central.
API reference (Javadoc/dartdoc) entra dentro do site do app, na subpasta api/ → fica em /aplicacoes/<app>/api/.

O que o repo do app precisa ter¶

docs/ no padrão da constituição (index, design/, rd/, guias/, img/, glossario.md com os termos específicos do projeto).
mkdocs.yml próprio (Material, pt-BR — copie de um app existente, ex. bi-transporte-xls).
.forgejo/workflows/docs.yml que builda e publica (idem, copie e ajuste).

Credenciais¶

O CI do app usa uma key do Garage com escrita no bucket docs-sites (provisionada pelo time, como qualquer key de app — ver Garage), configurada nos secrets do repo: DOCS_S3_ENDPOINT, DOCS_S3_ACCESS_KEY, DOCS_S3_SECRET_KEY.

É a única credencial do fluxo: não há token de Git nem chamadas entre CIs — quem quer publicar doc só precisa escrever no bucket.