UltraGXDocumentar uma KB
Documentar uma Knowledge Base é executar o pipeline sobre ela: a aba Executar pipeline lê a KB, a analisa e grava a documentação completa em uma subpasta da pasta de saída.
1. Escolher a fonte
| Fonte | O que se escolhe em Entrada | Quando usar |
|---|---|---|
| xpz — export XPZ / XML (GeneXus 7.5 ao 18) | um arquivo .xpz ou .xml | O caso geral. Serve para qualquer versão e em qualquer sistema operacional. A versão do GeneXus é detectada sozinha |
| gxtext — pasta de export de texto (src/ + ref/) | a pasta que contém src/ e ref/ | Se você já tem um export de texto do GeneXus 17 ou 18 |
| live — abrir a KB com o GeneXus instalado nesta máquina (conector) | a pasta da KB (a que contém o .gxw) | Windows com GeneXus X Evolution 1 a 18 instalado. Não é preciso exportar nada manualmente |
| mcp — pasta de dumps JSON | uma pasta de dumps JSON | Uso interno e suporte; normalmente não é usada |
Abaixo do seletor, o aplicativo explica cada fonte. Se a opção live aparecer desabilitada (requer o conector e uma instalação do GeneXus), a máquina não tem GeneXus ou está sendo usada uma cópia sem conector.
Como obter um XPZ
Na IDE do GeneXus: Knowledge Manager → Export, marque todos os objetos da KB e exporte para um arquivo .xpz. Em versões antigas (7.5, 8, 9) o caminho equivalente é Knowledge Manager → Distribute. Inclua tudo: quanto mais completo o export, melhores ficam as referências, o modelo de dados e os clusters.
Dicas:
- Exporte a partir da KB de desenvolvimento atualizada, não de uma cópia antiga.
- Se a KB for muito grande e a IDE não conseguir exportá-la de uma vez, exporte por partes (por módulo ou por tipo de objeto) e documente cada arquivo como um projeto separado, ou use a fonte live.
- Se você documentou a KB com uma versão do UltraGX anterior à 0.2.5 e os SDTs aparecem sem membros, execute novamente o pipeline (e, com a fonte live, a exportação) com a versão atual.
Fonte live e versão do GeneXus
Com live, o UltraGX abre a KB com o GeneXus instalado, a exporta para texto dentro da pasta do projeto (_source_text/) e depois executa o pipeline. Em Versão do GeneXus para a KB ao vivo, deixe auto (a partir da KB): o conector escolhe a instalação que corresponde à versão com que a KB foi salva. Se você tiver várias instalações da mesma versão (por exemplo, dois upgrades do GeneXus 18), pode forçar uma delas.
Antes de executar com live:
- Feche a KB na IDE do GeneXus. Uma KB só pode estar aberta em um processo por vez; se a IDE (ou outra ferramenta) a tiver aberta, a exportação espera ou falha.
- Conte com o fato de que a exportação ao vivo é a etapa mais lenta: o conector extrai cada objeto pelo SDK do GeneXus. Uma KB de 5.000 objetos pode levar mais de uma hora só para exportar. O log vai mostrando qual objeto está extraindo.
2. Nome do projeto e idioma
- Nome do projeto (subpasta de saída): por padrão, o nome do arquivo ou da pasta de entrada. Se você executar de novo com o mesmo nome, o projeto é regenerado na mesma pasta e as notas do usuário e a narrativa já gerada são preservadas.
- Idioma dos documentos: English, Español ou Português (BR). É o idioma da prosa dos documentos e do
visualizador. O
README.mdda raiz da saída fica sempre em inglês, porque foi pensado para agentes de IA. - gxtext: ignorar módulos referenciados (ref/): com as fontes gxtext e live, deixa de fora os objetos de módulos que a KB apenas referencia (bibliotecas do GeneXus e de terceiros). Acelera a execução e limpa o inventário; a contrapartida é que as chamadas a esses módulos ficam como referências externas.
3. Executar
Clique em Executar. O log abaixo mostra o avanço por etapas:
- Leitura: o motor lê a fonte e informa o objeto que está processando.
- Análise: regras, eventos, variáveis, acessos a dados e referências de cada objeto.
- Grafo, clusters, conhecimento e plano de reconstrução: relações entre objetos.
- Escrita: documentos, modelo de dados, diagramas e visualizador.
- Aceitação: controle de qualidade final.
Para não inundar a tela, o log escreve no máximo uma linha por segundo por etapa. Se uma linha se repetir com o mesmo objeto por algum tempo, o motor continua trabalhando em um objeto grande: ele não travou.
Quando termina bem, o status passa para concluído, o projeto aparece em Projetos e abre sozinho no Visualizador. Se a execução falhar, o status diz terminou com status erro e o log mostra o motivo (veja Solução de problemas).
Tempos de referência
| KB | Fonte | Tempo aproximado |
|---|---|---|
| 700 objetos | XPZ | menos de um minuto |
| 5.000 objetos | XPZ ou export de texto | de alguns minutos a meia hora |
| 5.000 objetos | live | a exportação (uma hora ou mais) mais o pipeline |
Os tempos dependem do disco e do tamanho do código de cada objeto. Na demo, soma-se uma consulta breve ao serviço de licenças.
Entradas recentes
Entradas recentes guarda as últimas quinze entradas usadas. Clique em uma para carregá-la de novo em Entrada.
Abrir um XPZ com clique duplo
Se ao instalar você marcou Abrir exports do GeneXus (.xpz) com o UltraGX, o clique duplo em um .xpz abre o aplicativo em Executar pipeline com a fonte xpz e o arquivo já carregado: só falta revisar o nome do projeto e o idioma e clicar em Executar.