Belgelere otomatik güncellenen ekran görüntüleri eklemek

 (interblah.net)
11 puan yazan GN⁺ 2 일 전 | 1 yorum | WhatsApp'ta paylaş
  • Çalışan bir web uygulamasında ekran görüntülerini otomatik yakalayan bir akış kurarak, yardım belgeleri derlenirken bunların da güncellenmesini sağlamak ve böylece UI değişikliklerinden sonra bile belge görsellerini güncel tutmak
  • Markdown içindeki SCREENSHOT yorumları hedef yol, yakalama yöntemi, CSS selector gibi talimatları taşır; build sürecinde bunlar okunur ve gerçek görsellerle doldurulur
  • Rake task, Capybara ve Cuprite üzerinden headless Chrome çalıştırır; işleri takım bazında gruplayarak bir kez giriş yaptıktan sonra birden fazla URL’yi dolaşıp yakalama yapar
  • Yakalama, element, full_page, viewport olmak üzere üç modu destekler; click, wait, crop, torn, hide gibi seçeneklerle açık durumdaki UI veya gereksiz öğeler de kontrol edilir
  • rails manual:build tek komutuyla ekran görüntüsü üretimi ve yardım sayfası build’i birlikte çalışır; kod ve belgeleri aynı PR ya da commit içinde hizalamak kolaylaşır ve manuel yakalama ile manuel crop kaynaklı sürtünme büyük ölçüde azalır

Otomatik güncellenen ekran görüntüsü yaklaşımı

  • Canlıda çalışan Jelly (ekipler için paylaşımlı e-posta gelen kutusu hizmeti) yardım merkezi, çalışan web uygulamasından ekran görüntülerini otomatik yakalayacak ve yeniden build alındığında bunları birlikte güncelleyecek şekilde kurgulanmış
  • Belgeler Markdown ile yazılıyor; Self-updating screenshots yazısındaki yapıya göre önce Redcarpet ile HTML’e dönüştürülüyor, ardından Rails uygulamasının ERB view’larıyla render ediliyor
  • Markdown içinde SCREENSHOT yorumları yer alıyor; burada hedef yol, yakalama yöntemi, CSS selector gibi talimatlar birlikte tutuluyor
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • Hemen altındaki görsel etiketi, sonucun yerleştirileceği konum olarak kullanılıyor
  • UI’daki renkler, buton konumu ya da metinler biraz değişse bile mevcut belge ekran görüntüleri hızla eskimeye yatkın; bu akış bu tür manuel güncelleme yükünü azaltıyor

Yakalama hattı ve bakım etkisi

  • İçeride Rake task, Capybara ve Cuprite üzerinden headless Chrome çalıştırarak tüm Markdown dosyalarındaki SCREENSHOT yorumlarını tarıyor
  • Ekran görüntüsü işleri takım bazında gruplanıyor; aynı takım için yalnızca bir kez giriş yapıldıktan sonra birden fazla URL sırayla ziyaret ediliyor
  • Desteklenen üç yakalama modu var
    • element: CSS selector ile belirli bir DOM öğesini yakalar
    • full_page: Tüm sayfayı yakalar; gerekirse yükseklik ölçütüne göre kırpılabilir
    • viewport: Yalnızca tarayıcı penceresinde o anda görünen alanı yakalar
  • Ayrıntı seçenekleri olarak click, wait, crop kullanılabiliyor; böylece butona tıklandıktan sonra ortaya çıkan durum veya animasyon sonrasındaki ekran da otomatik olarak yakalanabiliyor
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Butona basıp formu açtıktan sonra 200 ms bekler ve ardından belirli bir alanı kırparak yakalar
  • Ek seçenekler olarak torn ve hide da bulunuyor
    • torn, CSS clip-path kullanarak yırtık kağıt kenarı efekti uygular
    • hide, dev toolbar ya da cookie banner gibi ekranda görünmemesi gereken öğeleri geçici olarak gizler
  • Tüm hat, tek bir rails manual:build komutuyla çalışır; tüm ekran görüntüsü yakalamalarını ve yardım sayfası build’ini birlikte işler
  • Belge kaynakları public/manual/ altında basics, setup, advanced gibi bölümlere göre düzenlenmiştir
  • Build aşamasında bu Markdown dosyaları app/views/help/ altındaki ERB view’larına dönüştürülür; breadcrumb ve bölüm navigasyonu da birlikte üretilir
  • Özellik geliştirme ile yardım güncellemelerini aynı kod tabanında birlikte ele almak mümkün olduğu için, kod ile belgenin senkronizasyonunu aynı PR ya da aynı commit içinde korumak kolaylaşır
  • Kaydırma gerektiren öğeler, tıklanınca açılan popover’lar ve gereksiz kısımlardan kaçınmak için kullanılan crop gibi istisna durumları uygulamada daha fazla zaman gerektirmiş; ancak kurulduktan sonra yardım merkezi çok daha sık güncellenmeye başlanmış
  • UI değiştirildikten sonra build’i yeniden çalıştırıp sonucu commit etmek yeterli olduğundan, ekran görüntülerini her zaman güncel tutmak mümkün oluyor; manuel yakalama ve manuel crop kaynaklı sürtünme neredeyse tamamen ortadan kalkıyor

İlgili okumalar

1 yorum

 
GN⁺ 2 일 전
Hacker News yorumları
  • Ben de benzer şekilde bir .#screenshots derivation ekledim; ilk kurulum maliyeti yüksek olsa da sonrasında neredeyse hiç bakım gerektirmiyor.
    Ekran görüntülerini programatik olarak üretirken uygulamanın light/dark theme için iki sürümünü de birlikte oluşturup, prefers-color-scheme: dark ile uygun olanı değiştirmek yeterli oluyor.
    Bu tür şeyler GitHub README'lerinde de gayet iyi çalışıyor: https://github.com/CyberShadow/CyDo#readme
    • Bu yaklaşıma çok katılıyorum.
      Mobil uygulamalarda Nix ile tek seferlik bir Android emülatörü ayağa kaldırıp güncel ekran görüntülerini ürettim; önceden yapılandırma gerekmiyor ve çalıştırma sonrası veri de kalmıyor.
      Benim durumumda kurulumun kendisi o kadar da zor değildi; asıl zor olan fikri bulmaktı ve Nix kodunu da sevdiğim bir LLM ile tek seferde oluşturdum.
      Ekran görüntülerini manuel güncellemek dünyanın en zor işi değil ama upload-apk + take-screenshot + transfer-back-to-PC + edit akışı hep hafif sinir bozucu olduğundan sonunda neredeyse hiç yapmamaya başlıyorum.
  • Mobilde kod örnekleri için yatay kaydırma kesinlikle gerekli.
    Bağlamdan aşağı yukarı ne olduğu anlaşılabiliyordu ama yine de rahatsız ediciydi.
  • Bu, mobil projeler için gerçekten çok kullanışlı.
    Uygulama mağazalarında ekran görüntüleri zorunlu ve ekran boyutu ile yerelleştirme sayısı kadar görsel üretmek gerektiği için iş hızla zahmetli hale geliyor.
    Eskiden bunun için kendi script'lerimi yazıyordum; şimdi ise https://fastlane.tools/ gibi Fastlane araçları çok yardımcı oluyor.
    Mantık bulmaca oyunum Nonoverse için de Fastlane kullanıyorum; örnek ekran görüntülerini uygulama mağazası sayfasında görebilirsiniz: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    App Preview videolarının kaydını da birden fazla sahneyi içerecek şekilde otomatikleştirdim; merak eden olursa bunun hakkında ayrıca yazılabilecek bir konu bence.
    • İlgi çekici görünüyor ama bunun ücretli bir servis mi yoksa yerelde çalışan bir OS uygulaması mı olduğu konusunda pek emin olamadım.
  • Oldukça hoş.
    vibe coding ile yaptığım küçük casual oyunlar her zaman uygulamanın CLI üzerinden headless çalışabildiği, offscreen texture rendering, ekran görüntüsü komutu ve performans ölçümü yapabildiği bir halde başlıyor.
    Bunu eklemek neredeyse hiç zaman almıyor ve ajanın UI'ı otomatikleştirip önemli noktalara bakabilmesi için de bir kanal açıyor.
    Bu sayede ajanın ekran görüntülerini güncellemesini sağlamak da çok kolaylaşıyor.
    Build sürecine tamamen gömülü hali kadar temiz değil ama artık o kısmı da eklemeyi düşünüyorum.
    • Ben de aynısını yapıyorum.
      offscreen screenshot path ile world pos/camera view vector için CLI argümanlarım da var ve metin tabanlı bir giriş formatıyla script benchmark'ları çalıştırıyorum.
      Bu format; isimlendirilmiş segmentlerden oluşan birden çok satır, segment başına n oyun tick süresi ve her segmentin kontrol girdilerinden oluşuyor.
      Oyun kodu üzerinde çalışırken görselleri ve performansı A/B test etmek için bunu çok sık kullanıyorum.
    • Bu casual oyunların bağlantılarını paylaşabilir misin diye merak ediyorum.
      Ben de vibe coding'in oyun geliştirmeyi ne kadar kolaylaştırdığıyla çok ilgileniyorum.
      Adobe Flash döneminde bağımsız oyun ekosistemi gerçekten çok canlıydı; o zamandan beri neredeyse hiçbir şey bu kadar kolay geliştirme imkânı sunmadı.
      vibe coding, bu seviyeyi ilk kez aşan araç gibi görünüyor.
    • Bunu eklemek neredeyse hiç zaman almıyor sözü duruma göre değişir.
      Hangi engine'i kullandığını merak ettim.
  • Gerçekten çok hoş.
    Markdown belgelerinin içine ekran görüntüsü bildirimlerini satır içinde koyabilme fikri özellikle çok hoşuma gitti.
    Masaüstü uygulamam için farklı dillerde ve light/dark modlarda ekran görüntüleri üreten, gürültüyü temizleyen ve Windows/macOS pencere çerçeveleri ekleyen bir çözüm hazırlamıştım.
    Burada anlattım: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Şu anda ayrı bir script olduğu için bakımı epey can sıkıcı; bunu markdown/mdx'in bir parçası haline getirmeyi düşünmeliyim.
    Güzel bir ilham oldu.
  • Buna gerçekten çok sık ihtiyaç duydum.
    kimsenin fark etmediği X en iyi çalışması tarzı bir meme olarak bile kullanılabilir.
  • Bu güzel.
    Benim https://github.com/zombocom/rundoc projemde de benzer bir özellik var.
    Ana amaç tutorial oluşturma olduğu için, çalıştırılan komutların çıktısını da tekrar belgenin içine yerleştiriyor.
  • Burada gerçek zamanlı render yaklaşımı da mümkün olabilir diye düşünüyorum.
    Aracın canlı önizlemesini bir dikdörtgenin içine yerleştirmek gibi.
    Araç hafifse görsel olarak da en iyi seçenek olabilir ve tarayıcının erişilebilirlik ayarları ya da kullanıcı eklentileri gibi render ayarları da aynen yansıtılabilir.
  • e2e testleri çalıştırırken ekran görüntüsü üretimini de işin içine katmayı düşünmüştüm.
    Belgeler için docs/ klasörünü de aynı depoda tutup, belgeleri güncellerken yeni ekran görüntüsü gerektiğinde yeni bir test eklemek oldukça uyumlu bir yaklaşım gibi duruyor.
  • Güzel.
    Ben de birkaç yıl önce tam olarak bunu yapmaya başlamıştım ama sonunda https://picshift.io/ gibi daha genel amaçlı bir çözüme soyutladım.
    Yine de ekran görüntüsü kullanım senaryosu hâlâ çok hoşuma gidiyor ve bu projenin ilk adı da ScreenSync idi.
    • Güzel, iyi yapılmış ve bu tür farklı yaklaşımların bir arada bulunması sevindirici.