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õespymdownx.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ítepytestcobrindo 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¶
- Índice da documentação do workspace: docs/README.md
- Inventário de módulos do workspace: docs/modules.md