Cómo poner capturas de pantalla que se actualizan automáticamente en la documentación

 (interblah.net)
11 puntos por GN⁺ 22 일 전 | 1 comentarios | Compartir por WhatsApp
  • Crear un flujo que capture capturas de pantalla automáticamente desde una aplicación web en ejecución y las actualice junto con el build de la documentación de ayuda, para mantener las imágenes de la documentación siempre al día incluso después de cambios en la UI
  • Los comentarios SCREENSHOT dentro de Markdown contienen instrucciones como la ruta de destino, el método de captura y selectores CSS, y durante el proceso de build se leen para rellenarlos con imágenes reales
  • Una tarea de Rake ejecuta Chrome en modo headless mediante Capybara y Cuprite, agrupa el trabajo por equipo y, tras iniciar sesión una sola vez, recorre varias URL para capturarlas
  • La captura soporta tres modos: element, full_page y viewport, y con opciones como click, wait, crop, torn y hide también controla estados abiertos de la UI o elementos innecesarios
  • Con una sola ejecución de rails manual:build, se generan las capturas y se construyen las páginas de ayuda al mismo tiempo, lo que facilita alinear código y documentación en el mismo PR o commit y reduce mucho la fricción de las capturas y recortes manuales

Enfoque de capturas de pantalla que se actualizan automáticamente

  • El centro de ayuda de Jelly (servicio de bandeja de entrada de correo compartida para equipos) en producción está configurado para capturar capturas de pantalla automáticamente desde la aplicación web en ejecución y actualizarlas junto con cada nuevo build
  • La documentación está escrita en Markdown y, siguiendo el artículo Self-updating screenshots, se procesa a HTML con Redcarpet y luego se renderiza con vistas ERB de una app Rails
  • Dentro del Markdown se incluyen comentarios SCREENSHOT, donde se agregan instrucciones como la ruta de destino, el método de captura y selectores CSS
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • La etiqueta de imagen justo debajo se usa como ubicación donde irá el resultado
  • Cuando cambian aunque sea un poco los colores, la posición de los botones o los textos de la UI, las capturas existentes de la documentación se vuelven obsoletas con facilidad; este flujo reduce esa carga de actualización manual

Pipeline de captura y efecto en el mantenimiento

  • Internamente, una tarea de Rake ejecuta Chrome en modo headless mediante Capybara y Cuprite para escanear los comentarios SCREENSHOT de todos los archivos Markdown
  • El trabajo de capturas se procesa agrupado por equipo, de modo que dentro del mismo equipo se inicia sesión solo una vez antes de recorrer varias URL
  • Hay tres modos de captura soportados
    • element: captura un elemento específico del DOM mediante un selector CSS
    • full_page: captura la página completa y, si hace falta, puede recortarse según la altura
    • viewport: captura solo el área visible actual de la ventana del navegador
  • Como opciones detalladas, se pueden usar click, wait y crop, por lo que también es posible capturar automáticamente estados que aparecen después de hacer clic en un botón o pantallas posteriores a una animación
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Funciona abriendo el formulario al pulsar el botón, esperando 200 ms y luego capturando tras recortar a una región específica
  • También existen las opciones torn y hide
    • torn aplica un efecto de borde de papel rasgado usando CSS clip-path
    • hide oculta temporalmente elementos que no deberían aparecer en pantalla, como una dev toolbar o un banner de cookies
  • Todo el pipeline se ejecuta con un solo comando: rails manual:build, que procesa todas las capturas de pantalla y el build de las páginas de ayuda al mismo tiempo
  • Las fuentes de la documentación están organizadas en public/manual/ por secciones como basics, setup y advanced
  • En la etapa de build, estos archivos Markdown se convierten en vistas ERB bajo app/views/help/, y también se generan el breadcrumb y la navegación por secciones
  • Como el desarrollo de funcionalidades y la actualización de la ayuda pueden manejarse juntos dentro de la misma base de código, resulta más fácil mantener sincronizados el código y la documentación dentro del mismo PR o del mismo commit
  • Los casos especiales como elementos que requieren scroll, popovers que se abren con clic o recortes para evitar partes innecesarias exigieron más tiempo de implementación, pero una vez construido el sistema, el centro de ayuda empezó a actualizarse con mucha más frecuencia
  • Con solo cambiar la UI, volver a ejecutar el build y hacer commit del resultado, es posible mantener siempre actualizadas las capturas, eliminando casi por completo la fricción de la captura y el recorte manuales

Lecturas relacionadas

1 comentarios

 
GN⁺ 22 일 전
Comentarios de Hacker News
  • Yo también añadí algo parecido con .#screenshots derivation; el costo de configuración inicial es alto, pero después casi no requiere mantenimiento.
    Ya que generas las capturas por programa, también puedes crear las dos versiones de la app con light/dark theme y alternarlas según prefers-color-scheme: dark.
    Este tipo de cosas también funciona bien en los README de GitHub: https://github.com/CyberShadow/CyDo#readme
    • Coincido totalmente con este enfoque.
      En una app móvil hice que Nix levantara un emulador de Android desechable para generar capturas actualizadas; no requiere configuración previa y tampoco deja datos después de ejecutarse.
      En mi caso, la configuración en sí tampoco fue tan difícil; lo más complicado fue pensar la idea, y el código de Nix lo generé de una sola vez con mi LLM favorito.
      Actualizar capturas manualmente no es lo más duro del mundo, pero el flujo upload-apk + take-screenshot + transfer-back-to-PC + edit siempre es lo suficientemente molesto como para que al final casi nunca lo haga.
  • En móvil, el scroll horizontal en ejemplos de código es indispensable.
    Más o menos pude inferirlo por contexto, pero aun así fue incómodo.
  • Esto es realmente útil en proyectos móviles.
    En las tiendas de apps las capturas son obligatorias, y hay que generar imágenes para cada tamaño de pantalla y cada localización, así que se vuelve tedioso muy rápido.
    Antes escribía scripts a mano para esto, y ahora herramientas como Fastlane de https://fastlane.tools/ ayudan muchísimo.
    También uso Fastlane en mi juego de lógica Nonoverse, y se pueden ver capturas de ejemplo en la página de la App Store: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    Incluso tengo automatizada la grabación de videos de App Preview, incluyendo varias escenas, y si a alguien le interesa me parece un tema que daría para escribir un post aparte.
    • Me llama mucho la atención, pero no me queda claro si es un servicio de pago o una app del sistema operativo que corre localmente.
  • Está bastante genial.
    Los pequeños juegos casuales que hago con vibe coding siempre empiezan con la app ejecutándose en modo headless desde CLI, con renderizado a texturas fuera de pantalla, comando de captura y hasta instrumentación de rendimiento.
    Meter eso casi no toma tiempo, y además le da al agente una vía para automatizar la UI e inspeccionar puntos importantes.
    Gracias a eso también es muy fácil hacer que el agente actualice las capturas.
    No queda tan limpio como algo completamente integrado al proceso de build, pero ahora me dieron ganas de añadir también esa parte.
    • Yo hago exactamente lo mismo.
      También tengo argumentos de CLI para offscreen screenshot path y world pos/camera view vector, y corro benchmarks con un formato de entrada basado en texto.
      Ese formato consiste en varias líneas de segmentos con nombre, la duración de n ticks de juego por segmento y las entradas de control de cada segmento.
      Lo uso muchísimo para A/B testing de visuales y rendimiento mientras trabajo en el código del juego.
    • Me pregunto si podrías compartir algunos enlaces a esos juegos casuales.
      A mí también me interesa cuánto facilita vibe coding el desarrollo de juegos.
      En la época de Adobe Flash, el ecosistema de juegos indie era realmente vibrante, y desde entonces casi nada ha alcanzado ese nivel de facilidad para desarrollar.
      vibe coding parece la primera herramienta que de verdad supera ese nivel.
    • Eso de meter eso casi no toma tiempo depende del caso.
      Me da curiosidad saber qué engine usas.
  • Está realmente genial.
    Me gusta especialmente que puedas poner una declaración de captura en línea dentro de un documento Markdown.
    En mi app de escritorio armé una solución que genera capturas en varios idiomas y modos light/dark, elimina ruido y hasta les aplica marcos de ventana de Windows/macOS.
    Lo tengo documentado aquí: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Por ahora es un script aparte, así que mantenerlo es bastante molesto, pero voy a revisar la idea de integrarlo como parte del markdown/mdx.
    Me dio muy buena inspiración.
  • Esto es algo que de verdad necesitaba muy seguido.
    Da para usarlo como meme del tipo la mejor obra sobre X que nadie notará.
  • Está bueno.
    Mi https://github.com/zombocom/rundoc tiene una función parecida.
    Su propósito principal es generar tutoriales, así que también vuelve a insertar en el documento la salida de los comandos ejecutados.
  • Aquí también podría funcionar un enfoque de renderizado en tiempo real.
    Algo como poner la vista previa en vivo de la herramienta dentro de un rectángulo.
    Si la herramienta es liviana, hasta podría ser visualmente ideal, y además reflejaría tal cual la configuración de renderizado del navegador, las opciones de accesibilidad o los addons del usuario.
  • Cuando ejecuto pruebas e2e, alguna vez pensé en generar también las capturas al mismo tiempo.
    Si el docs/ de la documentación está en el mismo repositorio, y cada vez que al actualizar la documentación se necesitan capturas nuevas se agrega una prueba nueva, parece que encajaría bastante bien.
  • Está bien.
    Yo empecé a hacer exactamente esto hace unos años, pero al final lo abstraje hacia algo más general, como https://picshift.io/.
    Aun así, el caso de uso de capturas me sigue encantando, y de hecho el nombre original de ese proyecto era ScreenSync.
    • Bien hecho, y da gusto ver que convivan este tipo de enfoques diversos.