Ir para o conteúdo

federated-docs

Papel

Portal oficial de documentação do projeto HDT-AF (Human Digital Twin — Autonomous Federated Learning Framework), preparado para publicação no Read the Docs com MkDocs e tema Material for MkDocs (mkdocs-material).

O repositório é autocontido para permitir builds isolados no Read the Docs: um script determinístico (scripts/sync_docs.py) sincroniza a documentação técnica canônica de docs/, os README.md dos módulos em modules/*/, especificações OpenAPI, schemas MQTT, guias de infraestrutura/pesquisa, regras de governança e pré-renderiza diagramas PlantUML em SVG local.

Entrada: documentação técnica canônica do workspace (../../docs/, ../../modules/*/README.md, ../../docker/, ../../research/, ../../schemas/, ../../.agents/, ../../backlog.md).
Saída: portal estático HTML pesquisável (site/) e build validado para Read the Docs via .readthedocs.yaml e mkdocs.yml.

Estrutura

  • .readthedocs.yaml — configuração Read the Docs v2 (ubuntu-24.04, Python 3.12, mkdocs build --strict).
  • mkdocs.yml — navegação em Português (PT-BR), tema Material, busca, modo claro/escuro, Mermaid (mkdocs-mermaid2-plugin) e extensões pymdownx.
  • requirements.txt — dependências Python pinadas para build local e no Read the Docs.
  • scripts/sync_docs.py — sincronizador de documentos, reescritor de links, gerador de referência OpenAPI/backlog e pré-renderizador PlantUML → SVG.
  • scripts/build-docs.sh / scripts/serve-docs.sh — build estrito e servidor local de pré-visualização.
  • tests/test_sync_docs.py — suíte pytest cobrindo mapeamento, reescrita de links, Marp, PlantUML, OpenAPI, backlog e poda de arquivos obsoletos.
  • docs/ — conteúdo materializado e páginas iniciais do portal.

Comandos comuns

# Sincronizar a partir do workspace HDT-AF (com pré-renderização PlantUML → SVG)
python3 scripts/sync_docs.py

# Executar testes automatizados da ferramenta de sincronização
python3 -m pytest tests/ -v

# Build estrito (falha em links quebrados ou avisos de configuração)
mkdocs build --strict

# Servidor local de desenvolvimento (http://127.0.0.1:8000)
sh scripts/serve-docs.sh

Em ambientes sem o binário plantuml (como os servidores do Read the Docs), o build continua funcionando normalmente porque os SVGs pré-renderizados ficam versionados em docs/assets/diagrams/rendered/.

Documentação relacionada