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:
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.