Pular para conteúdo

0014 — Documentação no portal central

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-12 · Decidido em: 2026-06-11

Contexto

A documentação deste repo era arc42 em AsciiDoc, com diagramas PlantUML renderizados no build e o HTML embarcado no próprio JAR da aplicação (servido em /docs/). Esse modelo mantinha a doc presa ao artefato de deploy, exigia toolchain extra no build (AsciiDoctor + PlantUML, que precisa de Graphviz) e não se integrava ao portal de documentação da X-Adm, onde os demais projetos passaram a publicar.

A X-Adm consolidou uma constituição de documentação (versão 0.5.5) que define seis níveis, frontmatter padronizado, docs/ como fonte pública e publicação via MkDocs no portal central (docs.xadm.biz).

Decisão

Adotar a constituição X-Adm e migrar a documentação para MkDocs publicado no portal central, organizada em docs/ (visão geral, projeto, decisões, dev, operação, manual). A publicação passa a ser feita por um workflow dedicado de docs que sobe o site gerado para o storage do portal.

Em consequência, aposenta-se o pipeline arc42: removidos do build a geração de HTML AsciiDoctor, a geração de diagramas PlantUML e a opção que embarcava a doc no JAR (-PincludeDocsInJar); o job de documentação do CI também sai, e o deploy deixa de depender dele. Os diagramas passam a ser Mermaid inline nos docs de projeto.

Consequências

  • A doc deixa de viajar dentro do JAR e do endpoint /docs/ da aplicação — uma responsabilidade a menos no artefato de deploy.
  • O build fica mais simples e rápido (sem AsciiDoctor/PlantUML, sem dependência de Graphviz).
  • A doc fica visível no portal central junto dos outros projetos, com busca e frontmatter validado no CI.
  • O conteúdo arc42 anterior foi destilado para docs/ (decisões, projeto, operação, dev, manual); o original permanece no histórico do Git.
  • O docs/app.json passa a registrar a versão-base 0.5.5 da constituição; o hook de sessão avisa quando defasar.

Alternativas consideradas

  • Manter arc42 embarcado no JAR: acopla doc ao deploy, fica fora do portal central e exige toolchain pesada no build. Descartado.
  • Publicar o HTML arc42 numa branch de pages do Forgejo: resolveria a visibilidade, mas continuaria fora do padrão e do portal único da X-Adm. Descartado em favor do MkDocs central.