React Docgen ile React Bileşenleri için Dokümanlar Oluşturmak
Motivasyon
Geliştirdiğimiz projelerde hazırladığımız bileşenleri (component) dokümante etmek ve sunmak gibi saiklerle muhtelif araçlar kullanıyoruz. Bunların kimileri çatı (framework) veya kütüphanelere hususi olurken kimileri de birden fazla teknolojiyi destekleyebiliyorlar. Storybook, React Bluekit ve Cosmos bu alanda en yaygın kullanılan araçlardan birkaçı. Bu ve benzeri araçlar, kabaca iki görev görüyorlar.
Sunum
İlki, proje içerisinde kullandığımız bileşenleri, projeden izole bir ortamda render etmek. Bu sayede farklı girdi değerleriyle bileşenin nasıl şekilleneceğini ve hazırlanan bileşenin tasarımla uyumunu kontrol edebileceğimiz bir kılavuzu bize sağlıyorlar.
Doküman Oluşturmak
Diğeri ise bileşene dair doküman oluşturmak. Yine bunu da kabaca iki yönteme ayırabiliriz. İlki, bileşenden ayrı olarak oluşturulup elle içeriklerini güncellediğimiz dosyalar. Örneğin, Storybook’da bunlar BilesenAdi.stories.js isminde dosyalara karşılık geliyorlar. Bu dosyalarda doküman içerisindeki örneklerin prop değerleri ve sair açıklamalar yer alıyor. İkinci ve daha önemli yöntem ise otomatik olarak oluşturulan dokümanlar.
Aşağıdaki PostTagList isimli React bileşenini ele alalım. Biri başlık, diğeri etiketlerin tutulduğu dizi olmak üzere iki adet prop değeri alıyor. prop-types kütüphanesi vasıtasıyla başlık değerinin string ve zorunlu, etiketlerin de dizi ve yine zorunlu olması gerektiği belirtiliyor. Aynı zamanda başlık değeri boş gönderildiğinde varsayılan başlık değerinin de ne olması gerektiği tanımlanmış durumda. Birkaç tane de yorum satırı bloğu içermekte.
Bu örnekte bir React bileşeninde olması gerekenden fazla tek karakter dahi yazmamamıza rağmen tanımladığımız bilgiler bize bileşen hakkında çok fazla fikir vermekte. Bu bilgileri elbette farklı bir dokümana yazabilir ve bileşen üzerinde değişiklik oldukça oluşturduğumuz dokümanı elle güncelleyebiliriz. Fakat bu yöntem, pratikte hem yönetilmesi zor hem de hataya fazlasıyla teşne olacaktır.
Bunun yerine, bileşen içerisindeki bu bilgileri istediğimizde derli toplu ve konvansiyona uygun formatta dinamik olarak görsek, nasıl olurdu?
react-docgen
Yukarıda bahsi geçen Storybook gibi araçların temeli olan react-docgen kütüphanesinin yaptığı tam olarak bu aslında. react-docgen komut satırı arayüzü (CLI) veya doğrudan uygulama üzerinden React bileşenlerini render ederek içerisinde tanımlı olan bilgileri Abstract Syntax Tree marifetiyle ayrıştırıp JSON formatında bize veriyor.
react-docgen‘i global olarak kurup CLI üzerinden hızlıca örnek yapalım.
Kurulum tamamlandıktan sonra önceden yazdığımız PostTagList bileşeninin yolunu verelim ve hemen akabinde çıktımızı Python’ın JSON aracına yönlendirerek daha okunabilir hâle getirelim.
Aşağıdaki gibi JSON çıktısı elde ettik. Çıktıyı inceleyecek olursak, bileşen içerisinde kullandığımız isim ve yorum metinleri, prop değerleri için tanımladığımız veri tipleri, zorunluluk ve varsayılan değerleri kolayca okuyabileceğimiz ve programatik olarak ayrıştırabileceğimiz yapıda oluşturuldu.
Bileşen içerisindeki bu alanlardan herhangi birini değiştirip CLI aracını tekrar çalıştırdığımızda güncel JSON çıktısına alabileceğiz. Bu sayede bileşene dair dokümantasyon sürecini ilgili JSON dosyasını ayrıştırarak ister proje içerisinde ister de merkezi olarak otomatikleştirme imkânına sahip olacağız.
Sonuç
Storybook gibi araçlar sundukları birçok kullanışlı özellikle bileşenler özelinde dokümantasyon yönetim işini hakkıyla kotarmaktalar. Onların marifetlerine ayrıca değinmek niyetindeyim fakat bu araçları kullananlar fark edeceklerdir ki, içerdikleri özellikler daha temel kullanıma ihtiyaç duyanlara veya kendi çalışma ortamlarına özel bir doküman yönetim sistemi geliştirmek isteyenlere gereksiz bağımlılık olarak gözükecektir. Muhtemelen bu yazının ulaştığı çoğu kişinin ihtiyacını karşılayacaklardır fakat daha temel bir araç olmasından dolayı react-docgen‘den bahsetmek istedim.
