Inserindo screenshots com atualização automática na documentação

 (interblah.net)
11 pontos por GN⁺ 13 일 전 | 1 comentários | Compartilhar no WhatsApp
  • Criar um fluxo que captura screenshots automaticamente de uma aplicação web em execução e os atualiza junto com o build da documentação de ajuda, mantendo as imagens da documentação sempre atualizadas mesmo após mudanças na UI
  • Comentários SCREENSHOT no Markdown carregam instruções como caminho de destino, modo de captura e seletor CSS, e durante o processo de build eles são lidos e preenchidos com a imagem real
  • Uma Rake task executa o Chrome em modo headless via Capybara e Cuprite, agrupa o trabalho por equipe e, após fazer login uma vez, percorre várias URLs para capturar
  • A captura oferece três modos: element, full_page e viewport, além de opções como click, wait, crop, torn e hide para controlar também UIs abertas e elementos desnecessários
  • Com um único rails manual:build, a geração dos screenshots e o build das páginas de ajuda rodam juntos, facilitando alinhar código e documentação no mesmo PR ou commit e reduzindo bastante o atrito de capturas e recortes manuais

Abordagem de screenshots com atualização automática

  • A central de ajuda do Jelly (serviço de caixa de entrada de e-mail compartilhada para equipes) em produção foi estruturada para capturar screenshots automaticamente a partir da aplicação web em execução e atualizá-los junto nas reconstruções
  • A documentação é escrita em Markdown e, com base no artigo Self-updating screenshots, é processada em HTML com Redcarpet e depois renderizada nas views ERB do app Rails
  • Dentro do Markdown entram comentários SCREENSHOT, que carregam instruções como caminho de destino, modo de captura e seletor CSS
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • A tag de imagem logo abaixo é usada como o local onde o resultado será inserido
  • Quando cores da UI, posição de botões ou textos mudam mesmo que só um pouco, os screenshots antigos da documentação envelhecem rapidamente; esse fluxo reduz essa carga de atualização manual

Pipeline de captura e efeito na manutenção

  • Internamente, uma Rake task executa o Chrome em modo headless via Capybara e Cuprite para escanear os comentários SCREENSHOT de todos os arquivos Markdown
  • Os jobs de screenshot são processados em grupos por equipe, e para a mesma equipe o sistema é configurado para fazer login apenas uma vez antes de percorrer várias URLs
  • Há três modos de captura suportados
    • element: captura um elemento específico do DOM com seletor CSS
    • full_page: captura a página inteira e, se necessário, pode recortar com base na altura
    • viewport: captura apenas a área atualmente visível na janela do navegador
  • Como opções detalhadas, há click, wait e crop, permitindo capturar automaticamente estados exibidos após clicar em botões ou telas após animações
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • O comportamento é clicar no botão para abrir o formulário, esperar 200 ms e então recortar e capturar uma área específica
  • Também existem as opções adicionais torn e hide
    • torn aplica um efeito de borda de papel rasgado usando CSS clip-path
    • hide oculta temporariamente elementos que não devem aparecer na tela, como dev toolbar ou cookie banner
  • Todo o pipeline é executado com um único comando, rails manual:build, processando juntos todas as capturas de screenshot e o build das páginas de ajuda
  • O código-fonte da documentação está organizado em seções como basics, setup e advanced dentro de public/manual/
  • Na etapa de build, esses arquivos Markdown são convertidos em views ERB sob app/views/help/, com breadcrumb e navegação por seção também gerados junto
  • Como o desenvolvimento de funcionalidades e a atualização da ajuda podem ser tratados no mesmo codebase, fica mais fácil manter a sincronização entre código e documentação no mesmo PR ou no mesmo commit
  • Casos especiais como elementos que exigem rolagem, popovers que só abrem com clique e recortes para evitar partes desnecessárias exigiram mais tempo de implementação, mas depois de pronto o time passou a atualizar a central de ajuda com muito mais frequência
  • Basta mudar a UI, rodar o build novamente e fazer commit do resultado para manter os screenshots sempre atualizados, praticamente eliminando o atrito de capturas e recortes manuais

Leituras relacionadas

1 comentários

 
GN⁺ 13 일 전
Comentários do Hacker News
  • Eu também adicionei algo parecido com uma derivação .#screenshots; o custo de configuração inicial é alto, mas depois quase não exige manutenção
    Já que o programa gera as capturas de tela, dá para criar junto as duas versões do app com tema claro/escuro e alternar entre elas de acordo com prefers-color-scheme: dark
    Esse tipo de coisa também funciona bem em READMEs do GitHub: https://github.com/CyberShadow/CyDo#readme
    • Concordo fortemente com essa abordagem
      Em app mobile, fiz o Nix subir um emulador Android descartável para gerar capturas atualizadas, sem precisar de configuração prévia e sem deixar dados depois da execução
      No meu caso, a configuração em si nem foi tão difícil; o mais complicado foi ter a ideia, e o código Nix eu gerei de primeira com meu LLM favorito
      Atualizar capturas manualmente não é a tarefa mais sofrida do mundo, mas o fluxo upload-apk + take-screenshot + transfer-back-to-PC + edit é sempre incômodo o bastante para eu acabar quase nunca fazendo isso
  • No mobile, rolagem horizontal em exemplos de código é indispensável
    Deu para deduzir mais ou menos pelo contexto, mas ainda assim foi incômodo
  • Isso é muito útil em projetos mobile
    Em lojas de aplicativos, capturas de tela são obrigatórias, e você precisa gerar imagens para cada tamanho de tela e para cada localização, então isso fica trabalhoso muito rápido
    Antigamente eu escrevia scripts para isso; hoje ferramentas como Fastlane, tipo https://fastlane.tools/, ajudam bastante
    Uso Fastlane também no meu jogo de lógica Nonoverse, e dá para ver capturas de exemplo na página do app: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    Também automatizei a gravação de vídeos de App Preview, incluindo várias cenas, e acho que isso renderia um bom post separado para quem tiver curiosidade
    • Isso me interessou bastante, mas não ficou claro para mim se é um serviço pago ou um app de sistema operacional que roda localmente
  • Muito legal
    Os joguinhos casuais pequenos que faço com vibe coding sempre começam com o app podendo rodar em modo headless por CLI, com renderização em textura offscreen, comando de captura de tela e até medição de desempenho
    Isso quase não leva tempo para incluir e ainda cria um caminho para agentes automatizarem a UI e inspecionarem pontos importantes
    Por isso, fazer o agente atualizar as capturas também fica bem fácil
    Não é tão elegante quanto algo totalmente integrado ao processo de build, mas agora estou pensando em adicionar essa parte também
    • Eu faço exatamente a mesma coisa
      Também tenho argumentos de CLI para offscreen screenshot path e world pos/camera view vector, e rodo benchmarks com um formato de entrada baseado em texto
      Esse formato é composto por várias linhas de segmentos nomeados, a duração de n ticks de jogo por segmento e as entradas de controle de cada segmento
      Uso muito isso para testes A/B de visual e desempenho enquanto trabalho no código do jogo
    • Fiquei curioso se você poderia compartilhar alguns links desses jogos casuais
      Também tenho muito interesse em como vibe coding está facilitando o desenvolvimento de jogos
      Na época do Adobe Flash, o ecossistema de jogos indie era realmente vibrante, e desde então quase nada chegou perto daquele nível de facilidade de desenvolvimento
      Vibe coding parece ser a primeira ferramenta a superar aquilo
    • A frase Isso quase não leva tempo para incluir depende do caso
      Fiquei curioso sobre qual engine você usa
  • Muito bacana
    Gostei especialmente do fato de poder colocar uma declaração de screenshot inline dentro de um documento Markdown
    No meu app desktop, criei uma solução que gera capturas em vários idiomas e modos claro/escuro, remove ruído e até aplica molduras de janela do Windows/macOS
    Está documentado aqui: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Hoje isso está em um script separado, então a manutenção é bem chata; vou dar uma olhada em como incorporar isso como parte do markdown/mdx
    Foi uma ótima inspiração
  • Eu precisava muito de algo assim
    Dá até para usar como meme do tipo o melhor trabalho em X que ninguém percebe
  • Isso é bom
    Também há algo parecido no https://github.com/zombocom/rundoc que eu fiz
    Como o objetivo principal é gerar tutoriais, ele também reinsere no documento a saída dos comandos executados
  • Acho que uma abordagem de renderização em tempo real também poderia funcionar aqui
    Seria algo como colocar a prévia ao vivo da ferramenta dentro de um retângulo
    Se a ferramenta for leve, isso pode até ser visualmente ideal, e ainda refletiria as configurações de renderização do navegador, como ajustes de acessibilidade ou addons do usuário
  • Já pensei em aproveitar a execução de testes e2e para também gerar capturas de tela
    Se o docs/ ficar no mesmo repositório e você adicionar um novo teste quando precisar de uma nova captura ao atualizar a documentação, parece combinar bem
  • Bom
    Alguns anos atrás eu comecei a construir exatamente isso, mas acabei abstraindo para algo mais genérico, como https://picshift.io/
    Mesmo assim, continuo gostando muito do caso de uso de screenshots, e o nome original desse projeto era ScreenSync
    • Legal, ficou bem feito, e é bom ver que essas abordagens variadas coexistem