asciinema’ya Dokunmadan CLI Dokümantasyonunuz İçin Terminal Kayıtları Oluşturma: Kapsamlı Bir Rehber

asciinema’ya Dokunmadan CLI Dokümantasyonunuz İçin Terminal Kayıtları Oluşturma: Kapsamlı Bir Rehber

CLI (Komut Satırı Arayüzü) uygulamaları, geliştiriciler ve ileri düzey kullanıcılar için vazgeçilmez araçlardır. Ancak, bir CLI uygulamasının kullanımını ve yeteneklerini açık ve etkili bir şekilde belgelemek, çoğu zaman zorlu bir görev olabilir. Statik metin açıklamaları ve kod blokları, bazen karmaşık iş akışlarını veya interaktif süreçleri tam olarak yansıtmakta yetersiz kalır. İşte bu noktada terminal kayıtları devreye girer. Kullanıcıların komutları nasıl girdiğini, sistemin nasıl yanıt verdiğini ve uygulamanın genel deneyimini adım adım görmelerini sağlayan bu kayıtlar, dokümantasyonunuzun değerini katlayarak artırır. Geleneksel olarak asciinema bu alanda popüler bir çözüm olsa da, farklı ihtiyaçlar ve platformlar için alternatif yöntemlere başvurmak, dokümantasyon süreçlerinizi daha esnek ve güçlü hale getirebilir. Bu makalede, asciinema‘ya bağımlı kalmadan, çarpıcı ve bilgilendirici terminal kayıtları oluşturmanın çeşitli yollarını keşfedeceğiz.

Neden asciinema’ya Alternatifler Aramalıyız?

asciinema, terminal kayıtları oluşturmak ve paylaşmak için harika bir araçtır. Ancak, her projenin ve dokümantasyon ihtiyacının kendine özgü gereksinimleri vardır. Bazı durumlarda asciinema‘nın sunduğu .cast formatı veya web tabanlı oynatıcı bağımlılığı, belirli kısıtlamalar getirebilir.

Çıktı Formatı Sınırlamaları

asciinema‘nın birincil çıktı formatı, oynatılması için özel bir oynatıcı gerektiren .cast dosyalarıdır. Bu, kaydın bir web sitesine gömülmesini veya asciinema CLI aracıyla oynatılmasını gerektirir. Eğer dokümantasyonunuz için yaygın olarak desteklenen GIF, MP4 veya SVG gibi formatlara ihtiyacınız varsa, asciinema tek başına yeterli olmayabilir. Bu formatlar, dokümanlara kolayca entegre edilebilir, e-postalarda paylaşılabilir veya sunumlarda kullanılabilir.

Çevrimdışı ve Bağımsız Kullanım İhtiyacı

Bazı durumlarda, dokümantasyonun tamamen çevrimdışı çalışması veya harici bir hizmete bağımlı olmaması gerekebilir. asciinema‘nın web oynatıcısı veya asciinema.org platformu, internet bağlantısı gerektirebilir. Alternatif araçlar, tamamen bağımsız ve yerel olarak barındırılabilen çıktılar üretme olanağı sunar.

Kontrol ve Özelleştirme Eksikliği

asciinema ile kaydedilen terminal oturumlarının görünümü ve oynatma özellikleri üzerinde sınırlı kontrolünüz vardır. Arka plan rengi, yazı tipi, oynatma hızı gibi detayları doğrudan .cast dosyasında değiştirmek zordur. Diğer araçlar, bu tür görsel ve teknik özelleştirmeler için daha fazla esneklik sağlayabilir.

Görsel Terminal Kayıtları İçin Popüler Araçlar ve Yöntemler

asciinema‘nın ötesine geçerek terminal kayıtları oluşturmak için birçok farklı yaklaşım ve araç bulunmaktadır. Bu araçlar, ihtiyaçlarınıza göre GIF, MP4, SVG veya statik görüntüler üretebilir.

Metin Tabanlı Kayıtlar: script Komutu

Unix benzeri sistemlerde bulunan script komutu, terminal oturumunuzdaki tüm giriş ve çıktıları bir dosyaya kaydetmenin en temel yoludur. Bu, ham metin tabanlı bir kayıt sağlar ve daha sonra farklı formatlara dönüştürmek için bir temel oluşturabilir.

script my_session.txt
# Terminalde yapmak istediğiniz işlemleri yapın
exit

Bu komut, my_session.txt adlı bir dosyaya terminaldeki her şeyi kaydeder. Ancak, bu sadece metin çıktısıdır ve görsel bir kayıt değildir. Görselleştirmek için ek adımlar gereklidir.

Ekran Kayıt Araçları

Linux'ta Peek veya Byzanz, macOS'ta yerleşik ekran kayıt araçları veya Windows'ta ShareX gibi genel ekran kayıt yazılımları, belirli bir terminal penceresinin doğrudan video veya GIF kaydını alabilir. Bu yöntem, hızlı ve kolaydır ancak genellikle otomasyon ve hassas kontrol açısından sınırlıdır.

Özel Terminal Kayıt Araçları

Son yıllarda, özellikle dokümantasyon ve demo amaçlı olarak terminal kayıtları oluşturmaya odaklanmış birçok özel araç geliştirilmiştir. Bu araçlar, genellikle daha fazla otomasyon, özelleştirme ve farklı çıktı formatları sunar.

GIF ve MP4 Formatında Kayıt Üretimi: Detaylı İnceleme

GIF ve MP4, web dokümantasyonunda en çok tercih edilen görsel formatlardandır. Bu bölümde, bu formatlarda terminal kayıtları oluşturmak için kullanabileceğiniz güçlü araçlara odaklanacağız.

vhs (Video Host Script) ile Hızlı ve Otomatik GIF/MP4 Üretimi

vhs, özellikle CLI demoları ve dokümantasyon için tasarlanmış, modern ve kullanımı kolay bir araçtır. Bir DSL (Domain Specific Language) kullanarak terminal etkileşimlerini script'ler halinde tanımlamanıza olanak tanır ve bu script'lerden yüksek kaliteli GIF'ler veya MP4'ler üretir.

vhs Kurulumu ve Kullanımı

vhs'yi Go ile kolayca kurabilirsiniz:

go install github.com/charmbracelet/vhs@latest

Bir demo.tape dosyası oluşturarak terminal etkileşimlerinizi tanımlayın:

# demo.tape
Output "demo.gif"
Set Theme "Catppuccin"
Set FontSize 16
Set Width 1200
Set Height 600

Type "echo 'Merhaba, vhs!'" Sleep 1s
Enter
Type "ls -l" Sleep 500ms
Enter
Type "cd .." Sleep 500ms
Enter
Type "pwd" Sleep 500ms
Enter
Sleep 2s

Bu script'i çalıştırmak için:

vhs demo.tape

vhs, terminal etkileşimlerinizi otomatik olarak simüle eder ve belirtilen ayarlar doğrultusunda bir GIF veya MP4 dosyası oluşturur. Temalar, yazı tipleri, hız ayarları ve daha birçok özelleştirme seçeneği sunar.

termtosvg ile Ölçeklenebilir SVG Animasyonları

termtosvg, terminal oturumlarını SVG (Ölçeklenebilir Vektör Grafikleri) animasyonlarına dönüştüren harika bir araçtır. SVG'ler, çözünürlükten bağımsız olmaları ve genellikle daha küçük dosya boyutları sunmaları nedeniyle web dokümantasyonu için mükemmeldir.

termtosvg Kurulumu ve Kullanımı

termtosvg'yi pip ile kurabilirsiniz:

pip install termtosvg

Kullanımı, script komutuna benzer:

termtosvg record my_session.svg
# Terminalde yapmak istediğiniz işlemleri yapın
exit

Bu komut, terminal oturumunuzu my_session.svg adlı bir SVG animasyon dosyasına kaydeder. termtosvg, farklı temalar ve özelleştirme seçenekleri sunar.

ttyrec ve Dönüştürücüler (ttygif, tty2gif)

ttyrec, script komutunun daha gelişmiş bir versiyonudur ve terminal etkileşimlerini daha detaylı bir formatta kaydeder. Daha sonra bu ttyrec dosyalarını GIF'e dönüştürmek için ttygif veya tty2gif gibi araçlar kullanılabilir.

ttyrec Kullanımı

ttyrec my_session.ttyrec
# Terminalde işlemlerinizi yapın
exit

ttygif ile GIF'e Dönüştürme

ttygif my_session.ttyrec

Bu yöntem, daha eski ancak hala işlevsel bir yaklaşımdır ve bazı durumlarda basit ve hızlı GIF'ler oluşturmak için tercih edilebilir.

Statik Görüntüler ve Metin Tabanlı Çözümlerle Dokümantasyon

Her zaman animasyonlu bir kayda ihtiyacınız olmayabilir. Bazen statik bir ekran görüntüsü veya estetik bir kod bloğu, mesajınızı iletmek için yeterlidir.

script Komutu ile Ham Metin Kaydı

Yukarıda bahsedildiği gibi, script komutu terminal çıktısını düz metin olarak kaydeder. Bu, kopyalanabilir ve aranabilir metin örnekleri sağlamak için idealdir.

script -q /dev/null # Çıktıyı terminalde göstermeden kaydet
(
  echo "$ cd my-project"
  echo "$ ls -l"
  ls -l
) > terminal_output.txt

Bu, belirli komutların çıktısını bir dosyaya yönlendirerek düzenli metin blokları oluşturmanıza olanak tanır.

Kod Bloklarını Estetik Görüntülere Dönüştürme (carbon-now-sh, ray.so)

Bazen, sadece bir komutun veya çıktının güzel bir görüntüsünü paylaşmak istersiniz. carbon-now-sh veya ray.so gibi web tabanlı araçlar, kod bloklarınızı veya terminal çıktılarınızı şık, özelleştirilebilir görüntülere dönüştürmenizi sağlar. Bu araçlar, farklı temalar, yazı tipleri ve pencere stilleri sunarak görsel çekiciliği artırır.

Basit Ekran Görüntüleri

En basit ve hızlı yöntem, doğrudan terminal penceresinin ekran görüntüsünü almaktır. Bu, özellikle hızlı örnekler veya belirli bir anı yakalamak için kullanışlıdır. Ancak, bu yöntem otomasyon veya düzenleme yeteneklerinden yoksundur.

Terminal Kayıtlarını Otomatikleştirme ve CI/CD Entegrasyonu

Dokümantasyonunuzu güncel tutmanın anahtarı otomasyondur. Terminal kayıtlarını manuel olarak oluşturmak yerine, bunları CI/CD (Sürekli Entegrasyon/Sürekli Dağıtım) işlem hattınıza entegre ederek otomatik olarak güncelleyebiliriz.

GitHub Actions ile Otomatik Kayıt Oluşturma

vhs gibi araçlar, GitHub Actions gibi CI/CD platformlarıyla mükemmel bir şekilde entegre edilebilir. Her kod değişikliğinde veya belirli bir zaman çizelgesinde terminal kayıtlarınızı otomatik olarak yeniden oluşturabilirsiniz.

Örnek GitHub Actions İş Akışı

name: Generate CLI Demos

on:
  push:
    branches:
      - main
  workflow_dispatch: # Manuel çalıştırmaya izin verir

jobs:
  generate_demos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Install vhs
        run: go install github.com/charmbracelet/vhs@latest

      - name: Generate GIF
        run: vhs demo.tape

      - name: Upload GIF
        uses: actions/upload-artifact@v3
        with:
          name: cli-demo-gif
          path: demo.gif

Bu iş akışı, main branch'ine yapılan her push işleminde veya manuel olarak tetiklendiğinde demo.tape dosyasından bir GIF oluşturur ve bunu bir "artifact" olarak yükler. Bu sayede, dokümantasyonunuzdaki görseller her zaman güncel kalır.

Belgeleme Araçlarıyla Entegrasyon

MkDocs, Sphinx, Docusaurus gibi modern belgeleme araçları, genellikle Markdown veya reStructuredText gibi formatları destekler. Oluşturduğunuz GIF, MP4 veya SVG dosyalarını bu dokümanlara kolayca gömebilirsiniz.

## CLI Uygulamamızın Kullanımı

Uygulamamızın temel kullanımını aşağıdaki animasyonda görebilirsiniz:

![CLI Demo GIF](assets/demo.gif)

Daha fazla detay için [buraya tıklayın](#).

Bu tür bir entegrasyon, dokümantasyonunuzu canlı ve etkileşimli hale getirirken, bakım yükünü de azaltır.

Etkili Terminal Kayıtları Oluşturmak İçin İpuçları ve En İyi Uygulamalar

Harika araçlara sahip olmak bir başlangıçtır, ancak etkili terminal kayıtları oluşturmak için bazı en iyi uygulamaları takip etmek önemlidir.

Kısa ve Öz Olun

Kayıtlarınızın süresini mümkün olduğunca kısa tutun. Kullanıcıların dikkat süresi kısadır; önemli noktayı hızla iletin. Uzun ve karmaşık iş akışlarını birden fazla kısa kayda bölün.

Gizli Bilgileri Maskeleyin

API anahtarları, parolalar, hassas dosya yolları veya kişisel bilgiler gibi gizli verilerin kayıtlarda görünmediğinden emin olun. Gerekirse, sahte veriler kullanın veya bu alanları bulanıklaştırın/kapatın.

Tutarlı Bir Stil Kullanın

Terminal teması, yazı tipi boyutu, pencere boyutları gibi görsel öğelerde tutarlı olun. Bu, dokümantasyonunuzun profesyonel ve birleşik görünmesini sağlar. vhs gibi araçlar bu konuda büyük kolaylık sağlar.

Dosya Boyutunu Optimize Edin

Özellikle GIF'ler, büyük dosya boyutlarına sahip olabilir. Dosya boyutunu optimize etmek için çözünürlüğü, renk sayısını veya kare hızını düşürmeyi düşünün. gifsicle veya ffmpeg gibi araçlar bu konuda yardımcı olabilir. SVG animasyonları genellikle daha küçük boyutludur.

Erişilebilirliği Göz Ardı Etmeyin

Görsel kayıtlara alternatif metin (alt text) ekleyin. İşitme veya görme engelli kullanıcılar için kaydın içeriğini açıklayan bir transkript veya metin tabanlı bir alternatif sunmak, dokümantasyonunuzun erişilebilirliğini artırır.

Hata Durumlarını Gösterin

Sadece başarılı senaryoları değil, aynı zamanda yaygın hata durumlarını ve bu hataların nasıl giderileceğini gösteren kayıtlar da oluşturun. Bu, kullanıcıların sorunlarla karşılaştığında daha hazırlıklı olmalarını sağlar.

Sonuç

CLI dokümantasyonunuzu zenginleştirmek için asciinema'ya bağımlı kalmadan birçok güçlü alternatif bulunmaktadır. vhs ile otomatik GIF ve MP4 üretimi, termtosvg ile ölçeklenebilir SVG animasyonları veya script komutuyla ham metin kayıtları, her biri farklı ihtiyaçlara yönelik çözümler sunar. Bu araçları CI/CD işlem hatlarınıza entegre ederek, dokümantasyonunuzdaki terminal kayıtlarını otomatik olarak güncelleyebilir ve bakım yükünü azaltabilirsiniz. En iyi uygulamaları takip ederek, kullanıcılarınız için hem görsel olarak çekici hem de bilgilendirici kayıtlar oluşturabilir, böylece CLI uygulamanızın benimsenmesini ve kullanım kolaylığını önemli ölçüde artırabilirsiniz.

Sıkça Sorulan Sorular (SSS)

Hangi terminal kayıt aracı benim için en iyisidir?

En iyi araç, ihtiyaçlarınıza bağlıdır.

• Otomasyon ve yüksek kaliteli GIF/MP4 için: vhs
• Ölçeklenebilir, küçük boyutlu animasyonlar için: termtosvg
• Hızlı ve manuel ekran kaydı için: Peek (Linux), yerleşik ekran kaydediciler (macOS/Windows)
• Ham metin tabanlı kayıtlar için: script

Terminal kayıtlarını nasıl optimize edebilirim?

Kayıtlarınızı kısa tutun, gereksiz beklemeleri kaldırın, dosya boyutunu küçültmek için çözünürlüğü veya kare hızını düşürün (özellikle GIF'ler için). vhs ve termtosvg gibi araçlar, çıktı boyutunu kontrol etmenize yardımcı olacak birçok seçenek sunar.

Terminal kayıtlarını otomatikleştirmenin faydaları nelerdir?

Otomasyon, dokümantasyonunuzun her zaman güncel kalmasını sağlar, manuel hata riskini azaltır ve geliştiricilerin zamanından tasarruf eder. Yeni özellikler eklendiğinde veya mevcutlar değiştiğinde kayıtların otomatik olarak yeniden oluşturulması, dokümantasyonun ürünle senkronize kalmasını garantiler.

asciinema yerine bu araçları kullanmak ne zaman mantıklıdır?

Eğer dokümantasyonunuz için GIF, MP4 veya SVG gibi yaygın formatlara ihtiyacınız varsa, çevrimdışı kullanım önceliğinizse, kayıtların görünümü üzerinde daha fazla kontrol istiyorsanız veya kayıt oluşturma sürecini CI/CD'nize sıkıca entegre etmek istiyorsanız bu alternatifler daha mantıklı olabilir.

Mac veya Windows için önerilen araçlar var mı?

vhs (Go ile derlendiği için), termtosvg (Python ile) ve script (WSL veya Git Bash üzerinden) gibi birçok araç platformdan bağımsız olarak çalışır. Ayrıca, macOS'ta yerleşik ekran kayıt araçları, Windows'ta ShareX gibi genel ekran kaydediciler de kullanılabilir.