| Title: | Living Documents for trama Analyses |
|---|---|
| Description: | Turns a trama analysis into a finished document: a Quarto file of the project where the text belongs to the author and managed regions belong to trama. Results of flow nodes are materialized next to the document (tables, figures, sanitized models, tests) and referenced by regions that are refreshed when the analysis changes, without ever touching the author's text. Documents start from Quarto extension templates (a gallery to create, edit, duplicate, import and export them, with built-in academic ABNT, consulting report, article, slides and dashboard templates) and author profiles, and render locally to HTML, PDF (Typst), Word, revealjs slides and dashboards. Charts follow a light theme derived from the template's brand. A web page template turns models into predictors that run in the browser through WebR, and any document can be published to GitHub as an RO-Crate research package, with a release and a GitHub Pages site rendered by GitHub Actions. It is a trama plugin, not a block collection: it has no nodes. When installed, the trama editor shows a Documents panel (with a template gallery) and an 'insert into document' item in the card menu. |
| Authors: | Pedro Mambelli Fernandes [aut, cre] |
| Maintainer: | Pedro Mambelli Fernandes <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.5.0 |
| Built: | 2026-10-22 10:39:48 UTC |
| Source: | https://github.com/uaipedro/trama |
Um passo de leitura no GitHub: o workflow começou, terminou, falhou (em
que etapa)? A release saiu? A página responde? Grava e devolve o estado,
com etapa em enviado, actions, release, no_ar ou falhou.
tr_documento_acompanhar(documento, projeto = NULL)tr_documento_acompanhar(documento, projeto = NULL)
documento |
Caminho do |
projeto |
Um |
O estado do envio (ver tr_documento_publicar()), com actions,
release e log quando houver; NULL se o documento nunca foi
publicado deste projeto.
Para cada região desatualizada (ou todas, com forcar), recalcula o
valor, materializa e compara pelo hash do resultado: igual, nada é
reescrito; diferente, reescreve a pasta _trama/<chave>/ e, se o corpo da
região mudou, só as linhas dela. Regiões em conflito e órfãs não são
tocadas. Antes de gravar, confere que o texto de fora das regiões ficou
idêntico, byte a byte.
tr_documento_atualizar( documento, projeto = NULL, regioes = NULL, forcar = FALSE )tr_documento_atualizar( documento, projeto = NULL, regioes = NULL, forcar = FALSE )
documento |
Caminho do |
projeto |
Um |
regioes |
Chaves das regiões a atualizar; |
forcar |
|
data.frame com regiao, estado (atualizada, igual,
conflito, orfa, indisponivel, erro) e mensagem.
Genérico S3 pela classe do valor. Métodos embutidos: tabela
(data.frame), gráfico (ggplot), modelo (tr_models_fit, reduzido por
trama.models::tr_models_strip()) e teste (tr_test). Para os demais, o
método padrão usa o report do tipo da porta (trama::tr_type(report =)),
o mesmo que o relatório exportado usa; sem ele, a parte sai com erro.
tr_documento_componente(x, ctx)tr_documento_componente(x, ctx)
x |
O valor do nó. |
ctx |
Lista com |
Uma coleção estende registrando um método para a classe dos seus valores
(S3method(trama.documentos::tr_documento_componente, minha_classe), ou
registerS3method() no .onLoad, se o plugin for só sugerido).
Monta documentos/<nome>/ no projeto: o .qmd (YAML com título, autor
do perfil, data, formatos do modelo e o fluxo de origem, mais o esqueleto
do modelo), a cópia da extensão em _extensions/<modelo>/, o _brand.yml
e um _quarto.yml que manda a saída do render para _saida/. É o único
momento em que o trama escreve fora das regiões.
tr_documento_criar( nome, projeto = ".", modelo = "basico", perfil = NULL, titulo = NULL, fluxo = "main" )tr_documento_criar( nome, projeto = ".", modelo = "basico", perfil = NULL, titulo = NULL, fluxo = "main" )
nome |
Nome do documento (letras, dígitos, |
projeto |
Pasta do projeto (ou um |
modelo |
Nome do modelo ( |
perfil |
Nome do perfil de autor; |
titulo |
Título; |
fluxo |
Fluxo do projeto de onde vêm as regiões. |
O YAML do esqueleto pode pedir campos do perfil: um valor
"{{perfil.orientador}}" vira o orientador do perfil (e some, se o perfil
não tem), e "{{ano}}" vira o ano corrente. É assim que o modelo UFLA
preenche orientador e curso.
O caminho do .qmd.
Não calcula nada: compara o conteúdo de cada região com o hash que o trama gravou e a chave do store de agora com a da última materialização.
tr_documento_estado(documento, projeto = NULL)tr_documento_estado(documento, projeto = NULL)
documento |
Caminho do |
projeto |
Um |
atualizada: a região mostra o resultado de agora;
desatualizada: o nó, o que ele lê ou as opções mudaram desde então
(atualizar confirma pelo resultado e só reescreve se ele mudou);
conflito: o conteúdo foi editado à mão; atualizar não toca nela;
orfa: o nó (ou a porta) saiu do fluxo; a região fica até a pessoa decidir;
indisponivel: o nó está no fluxo, mas a coleção dele não carregou;
duplicada: outra região com a mesma chave veio antes no texto (cópia
à mão); só a primeira é do trama, e esta não é tocada.
data.frame com regiao, no, porta, estado e linha, na
ordem do texto.
Os formatos que o YAML do documento declara (vindos do modelo), nos nomes
de tr_documento_renderizar().
tr_documento_formatos(documento)tr_documento_formatos(documento)
documento |
Caminho do |
Vetor de texto, como c("html", "pdf", "docx").
Calcula (ou lê do cache) o valor do nó, materializa em _trama/<no>/ ao
lado do documento e insere a região ::: {#trama-<no> .trama} que o
referencia. Só acrescenta linhas: o texto existente não muda.
tr_documento_inserir( documento, no, projeto = NULL, porta = NULL, apos = NULL, opcoes = list(), aceitar_dados_treino = FALSE )tr_documento_inserir( documento, no, projeto = NULL, porta = NULL, apos = NULL, opcoes = list(), aceitar_dados_treino = FALSE )
documento |
Caminho do |
no |
Id do nó no fluxo do documento (YAML |
projeto |
Um |
porta |
Porta de saída; |
apos |
Onde inserir: |
opcoes |
Lista de opções da região, gravadas no cabeçalho como
|
aceitar_dados_treino |
|
Invisível: lista com regiao (a chave) e avisos.
_trama/ o que nenhuma região usaUma pasta fica se há região com a chave dela ou se o texto ainda cita o
caminho (região mantida como texto da pessoa), em qualquer .qmd da
pasta do documento.
tr_documento_limpar(documento)tr_documento_limpar(documento)
documento |
Caminho do |
Invisível: as pastas apagadas.
Documentos do projeto
tr_documento_listar(projeto = ".")tr_documento_listar(projeto = ".")
projeto |
Pasta do projeto (ou um |
data.frame com nome, caminho, fluxo, modelo e regioes.
publicar/publish do projeto para documentosPara cada nó publicar/publish (da coleção trama.publicar, que deixou
de existir) em qualquer fluxo do projeto, cria um documento do modelo
Página web com o que o nó tinha: título, resumo, palavras-chave, autores
(com ORCID), licenças, tipo de versão, repositório privado e aceite de
dados de treino no YAML; o corpo segue o layout do nó (cabeçalho, textos,
cada item ligado como região, o diagrama). O endereço da publicação já
feita passa a ser do documento (tr_documento_publicacoes()), e a próxima
publicação continua no mesmo repositório, na versão seguinte. Depois tira
o nó (e as arestas que chegavam nele) do fluxo e trama.publicar da lista
de coleções do trama.json.
tr_documento_migrar_publicar(projeto = ".")tr_documento_migrar_publicar(projeto = ".")
projeto |
Pasta do projeto (ou um |
Item que não pôde virar região (o nó falha, o modelo carrega dados de treino sem o aceite) vira uma nota no texto, para inserir de novo à mão.
data.frame com fluxo, no, documento (caminho relativo ao
projeto), regioes (quantas entraram) e avisos; zero linhas se não
havia nada a migrar.
O que a galeria mostra e edita: título, descrição, formatos, cores, fontes, logo, capa, CSL e o perfil sugerido, mais se o modelo é válido.
tr_documento_modelo(nome)tr_documento_modelo(nome)
nome |
Nome do modelo (a pasta), como em |
Lista com nome, titulo, descricao, formatos,
formatos_desligados, origem ("embutido" ou "usuario"),
sobre_embutido (cópia do usuário de um embutido), caminho, perfil,
cores e fontes (listas nomeadas como em
tr_documento_modelo_editar()), logo (caminho ou NULL), capa
(TRUE, FALSE ou NULL se o modelo não diz), csl (nome do arquivo
ou NULL), valido e problemas.
Os modelos do usuário moram em tools::R_user_dir("trama", "data")/modelos/.
tr_documento_modelo_criar() parte de um modelo existente (base) e
aplica as edições; tr_documento_modelo_duplicar() copia tal como está;
tr_documento_modelo_editar() muda os campos dados (os demais ficam);
tr_documento_modelo_remover() apaga um modelo do usuário (o embutido de
mesmo nome, se houver, volta a valer).
tr_documento_modelo_criar( nome, titulo = NULL, base = "basico", descricao = NULL, formatos = NULL, cores = NULL, fontes = NULL, logo = NULL, capa = NULL, csl = NULL, perfil = NULL ) tr_documento_modelo_duplicar(modelo, nome, titulo = NULL) tr_documento_modelo_editar( nome, titulo = NULL, descricao = NULL, formatos = NULL, cores = NULL, fontes = NULL, logo = NULL, capa = NULL, csl = NULL, perfil = NULL ) tr_documento_modelo_remover(nome)tr_documento_modelo_criar( nome, titulo = NULL, base = "basico", descricao = NULL, formatos = NULL, cores = NULL, fontes = NULL, logo = NULL, capa = NULL, csl = NULL, perfil = NULL ) tr_documento_modelo_duplicar(modelo, nome, titulo = NULL) tr_documento_modelo_editar( nome, titulo = NULL, descricao = NULL, formatos = NULL, cores = NULL, fontes = NULL, logo = NULL, capa = NULL, csl = NULL, perfil = NULL ) tr_documento_modelo_remover(nome)
nome |
Nome do modelo: letras minúsculas, dígitos e |
titulo |
Nome de exibição na galeria ( |
base |
Modelo de onde |
descricao |
Uma frase sobre o modelo. |
formatos |
Formatos habilitados, entre |
cores |
Lista ou vetor nomeado de cores |
fontes |
Lista ou vetor nomeado de famílias: |
logo |
Caminho de uma imagem (png, svg, jpg), copiada para o modelo;
|
capa |
|
csl |
Caminho de um estilo de citação |
perfil |
Perfil de autor que o modelo sugere
( |
modelo |
Modelo a duplicar. |
Editar um embutido cria a cópia do usuário com o mesmo nome, que passa a valer em documentos novos. Documento já criado leva a cópia do modelo de quando foi criado: mudar o modelo não muda documento existente.
Invisível: o modelo, como tr_documento_modelo(); remover
devolve o nome.
O zip leva a pasta do modelo (<nome>/_extension.yml, …). Importar aceita
esse formato, a pasta solta na raiz do zip e o formato das extensões Quarto
publicadas (_extensions/<nome>/ com o template.qmd na raiz). O modelo é
conferido antes de entrar: zip inválido não deixa nada na galeria.
tr_documento_modelo_exportar(nome, arquivo = NULL) tr_documento_modelo_importar(arquivo, nome = NULL, substituir = FALSE)tr_documento_modelo_exportar(nome, arquivo = NULL) tr_documento_modelo_importar(arquivo, nome = NULL, substituir = FALSE)
nome |
Nome do modelo. Na importação, |
arquivo |
Caminho do zip. Na exportação, |
substituir |
Importar por cima de um modelo do usuário de mesmo nome. |
O caminho do zip (exportar) ou, invisível, o modelo importado
(tr_documento_modelo()).
A galeria: os embutidos e os do usuário (que têm precedência sobre o
embutido de mesmo nome). Modelo inválido aparece, com valido = FALSE e o
problema, em vez de sumir ou quebrar a lista.
tr_documento_modelos()tr_documento_modelos()
data.frame com nome, titulo, formatos (separados por
vírgula), origem ("embutido" ou "usuario"), caminho,
descricao, perfil (o perfil de autor que o modelo sugere, ou NA),
sobre_embutido, valido e problema (os problemas, separados por
"; ", ou NA).
tr_documento_modelo() para um modelo em detalhe e
tr_documento_modelo_criar() para criar, editar, duplicar e remover.
A pasta que "Publicar no GitHub" envia, e que se pode conferir antes:
o documento como index.qmd, a pasta dele (sem _saida/ nem arquivos
ocultos; de _trama/, só o que o texto usa), flow.json, fluxo.svg,
dados-entrada.json, ambiente.json, README.md, CITATION.cff,
LICENSE, _variables.yml com a versão e a citação, e o
ro-crate-metadata.json. Bloqueios de tr_documento_publicacao() param
a montagem.
tr_documento_pacote( documento, dir, projeto = NULL, versao = NULL, repositorio = "", data = Sys.Date() )tr_documento_pacote( documento, dir, projeto = NULL, versao = NULL, repositorio = "", data = Sys.Date() )
documento |
Caminho do |
dir |
Pasta de destino (criada; o conteúdo anterior é apagado). |
projeto |
Um |
versao |
Versão do pacote ( |
repositorio |
Endereço do repositório da publicação (vai para a citação). |
data |
Data da publicação ( |
Invisível: list(dir, arquivos, publicacao).
tr_documento_componente() devolveO motor grava arquivos em _trama/<chave>/ ao lado do documento e põe
corpo dentro da região. O corpo referencia os arquivos pelo caminho
relativo ao documento (ctx$arquivo("tabela.md")), para que o render não
precise recalcular nada nem ter o store do projeto.
tr_documento_parte( tipo, titulo = "", arquivos = list(), corpo = character(), metadados = list(), dados_treino = NULL, avisos = character(), erro = NULL )tr_documento_parte( tipo, titulo = "", arquivos = list(), corpo = character(), metadados = list(), dados_treino = NULL, avisos = character(), erro = NULL )
tipo |
Texto curto do que é a parte ( |
titulo |
Título da parte (legenda de figura e tabela). |
arquivos |
Lista nomeada: nome do arquivo (sem |
corpo |
Linhas de Markdown que vão dentro da região. |
metadados |
Lista que descreve a parte no pacote RO-Crate:
|
dados_treino |
|
avisos |
Textos para quem insere (não bloqueiam). |
erro |
Texto: a parte não entra. |
Objeto de classe tr_documento_parte.
tr_documento_perfis() lê todos; tr_documento_perfil() devolve um (o
padrão, sem nome); tr_documento_perfil_salvar() cria ou substitui;
tr_documento_perfil_remover() apaga. Ficam em
tools::R_user_dir("trama", "data")/perfis.yml.
tr_documento_perfis() tr_documento_perfil(perfil = NULL) tr_documento_perfil_salvar( perfil, nome, email = NULL, orcid = NULL, instituicao = NULL, curso = NULL, orientador = NULL, logo = NULL, padrao = FALSE ) tr_documento_perfil_remover(perfil)tr_documento_perfis() tr_documento_perfil(perfil = NULL) tr_documento_perfil_salvar( perfil, nome, email = NULL, orcid = NULL, instituicao = NULL, curso = NULL, orientador = NULL, logo = NULL, padrao = FALSE ) tr_documento_perfil_remover(perfil)
perfil |
Nome do perfil (letras, dígitos, |
nome |
Nome da pessoa, como sai no documento. |
email, orcid, instituicao, curso, orientador, logo
|
Opcionais. O ORCID é
conferido (formato e dígito verificador). |
padrao |
|
tr_documento_perfis(): lista com padrao (nome ou NULL) e
perfis (lista nomeada). tr_documento_perfil(): o perfil (lista com
perfil e os campos) ou NULL. As demais, invisível, o perfil salvo ou
o nome removido.
Renderiza em HTML (ou nos slides ou no dashboard, se o documento não tem
HTML) e serve _saida/ num servidor local
(http://127.0.0.1:<porta>/). O servidor fica de pé até
tr_documento_previa_parar() ou o fim da sessão do R; uma nova prévia do
mesmo documento reaproveita o servidor.
tr_documento_previa(documento, abrir = interactive(), tempo = 300) tr_documento_previa_parar(previa = NULL)tr_documento_previa(documento, abrir = interactive(), tempo = 300) tr_documento_previa_parar(previa = NULL)
documento |
Caminho do |
abrir |
Abrir no navegador. |
tempo |
Segundos até desistir. |
previa |
Uma prévia; |
Objeto tr_documento_previa: lista com url, pasta e
documento.
Não toca no GitHub nem grava nada: lê o YAML e o estado das regiões e diz
o que vai no pacote, o que merece atenção (avisos) e o que impede a
publicação (erros).
tr_documento_publicacao( documento, projeto = NULL, desatualizada = c("erro", "aviso") )tr_documento_publicacao( documento, projeto = NULL, desatualizada = c("erro", "aviso") )
documento |
Caminho do |
projeto |
Um |
desatualizada |
Região desatualizada é |
Do YAML do documento: title, author (nomes e, se houver, orcid,
conferido pelo dígito verificador), description (ou abstract) e
keywords. De trama: publicar:: licenca (do conteúdo, padrão
CC-BY-4.0), licenca-codigo (padrão MIT), versao (tipo da próxima:
menor, correção ou maior), privado (repositório da publicação
privado; Pages privado exige plano pago) e aceitar-dados-treino (publicar
modelos que carregam linhas do treino, que de outro modo são recusados) e
incluir-dados (arquivos de dados que estejam na pasta do documento).
Bloqueiam: falta de título ou de autor, ORCID que não confere, licença
desconhecida, região desatualizada (atualize antes), região sem a pasta
materializada, modelo com dados de treino sem o aceite, arquivo acima de
100 MB, documento sem formato HTML ou com mais de um (a página do GitHub
Pages), arquivo de dados na pasta do documento sem incluir-dados e
arquivo da pasta com o nome de um que o pacote gera. Os outros arquivos da
pasta, que vão junto, saem nos avisos.
Objeto tr_documento_publicacao: lista com documento,
metadados, regioes, avisos e erros.
Em que repositório cada documento é publicado, a página, a última versão
enviada e quando. Mora no trama.json (chave publicacoes, pelo caminho
do documento no projeto): é configuração do PROJETO, não vai no documento
nem no pacote publicado. Estado do Actions e versões ao vivo se leem do
GitHub (trama.github); isto é só o endereço de cada publicação.
tr_documento_publicacoes(projeto = ".")tr_documento_publicacoes(projeto = ".")
projeto |
Pasta do projeto (ou um |
data.frame com documento (caminho relativo ao projeto), repo,
url, pagina (base do Pages), ultimo, versao, tag e data;
zero linhas sem publicação.
Atualiza as regiões, confere (tr_documento_publicacao()), monta o pacote
(tr_documento_pacote()) com a próxima versão livre e o envia num commit
atômico ao repositório da publicação, com a tag vX.Y.Z que dispara o
workflow. A conta é a do trama.github (menu GitHub do editor, ou
GITHUB_PAT). Volta logo: o Actions leva um minuto ou dois, e
tr_documento_acompanhar() diz em que etapa está.
tr_documento_publicar( documento, projeto = NULL, repositorio = NULL, confirmado = FALSE, atualizar = TRUE )tr_documento_publicar( documento, projeto = NULL, repositorio = NULL, confirmado = FALSE, atualizar = TRUE )
documento |
Caminho do |
projeto |
Um |
repositorio |
|
confirmado |
Já confirmado (ver acima). |
atualizar |
Atualizar as regiões antes ( |
Pede confirmação (devolve confirmar, sem tocar no GitHub) antes de criar
um repositório privado (Pages privado exige plano pago) e antes de enviar
a um repositório que já existe sem nenhuma versão vX.Y.Z (o envio
substitui o conteúdo dele). Bloqueios saem em bloqueios.
Lista: bloqueios, ou confirmar (texto) e repo, ou o estado
do envio (documento, repo, url, versao, tag, sha, pagina,
ultimo, etapa = "enviado", detalhe).
Usa o formato do modelo que o YAML do documento declara
(basico-typst para "pdf", por exemplo); sem ele, o formato puro do
Quarto. Não atualiza regiões: renderiza o que está no arquivo (chame
tr_documento_atualizar() antes, se quiser os resultados de agora).
tr_documento_renderizar( documento, formato = c("html", "pdf", "docx", "revealjs", "dashboard"), tempo = 300 )tr_documento_renderizar( documento, formato = c("html", "pdf", "docx", "revealjs", "dashboard"), tempo = 300 )
documento |
Caminho do |
formato |
|
tempo |
Segundos até desistir. |
O caminho do arquivo gerado, em _saida/ (slides em
_saida/slides/, dashboard em _saida/painel/).
manter: a versão que está no texto passa a ser da pessoa: as cercas
da região saem e o conteúdo fica como texto comum, que o trama não toca
mais. A pasta _trama/<chave>/ é congelada como
_trama/<chave>--mantida/ (e o texto passa a citá-la), para que um
novo "inserir" do mesmo nó não mude o que a pessoa ficou;
trazer: descarta a edição e põe a versão do trama de agora (não vale
para órfã);
remover: apaga a região do texto.
tr_documento_resolver( documento, regiao, acao = c("manter", "trazer", "remover"), projeto = NULL, confirmar = FALSE )tr_documento_resolver( documento, regiao, acao = c("manter", "trazer", "remover"), projeto = NULL, confirmar = FALSE )
documento |
Caminho do |
regiao |
Chave da região ( |
acao |
|
projeto |
Um |
confirmar |
Ver acima. |
Região em conflito com cercas ::: dentro (a pessoa pôs um callout, por
exemplo) pode ter o fim diferente do que a pessoa imagina: trazer e
remover apagariam essas linhas, e só seguem com confirmar = TRUE.
Invisível: lista com regiao e removidas, as linhas que saíram
do texto.
Contrato de plugin do trama (ver trama::tr_plugins()): o editor carrega
inst/trama/documentos.js (o botão Documentos na barra e o item "Inserir
no documento…" no menu do card) e liga o server abaixo a cada sessão. O
canal é próprio: o JS manda input$trama_documentos ({acao, ...}) e o R
responde com a mensagem trama_documentos ({tipo, ...}).
trama_plugin()trama_plugin()
Lista com js, css e server.