AsciiDoc ve Knitr ile Ruby Algoritma Belgeleri

Önemsiz olmayan her projenin belgelere ihtiyacı vardır ve gerçekten okunabilmesi ve kullanılabilmesi için harika açıklamalar ve hatta çizimlerle ilgi çekici olması gerekir. Mühendisler, genellikle belirli bir işte kapsamlı deneyime sahip olmadan iş sorunlarını çözmek için yazılımlar yaparlar, bu nedenle işi belgelemek, yazılımı belgelemek kadar önemlidir.

Belgeler olaydan sonra eklenebilir, ancak kodlamadan önce işlevsel bir belirtim yazmanın çok yardımcı olduğunu düşünüyorum. İşlevsel bir belirtim, ekibin disiplinlerdeki her üyesi için bir hakikat kaynağıdır ve uygulamadan önce üst düzey tasarımı zorlayarak boşa harcanan çabayı önler. Bu yazıda, uygulamanın ne yapması gerektiğini açıklamak ve geliştirme sırasında bir referans olması için örnek bir Ruby on Rails projesi için prototiplemeden işlevsel bir belirtim yazmaya kadar örnek bir projeden geçeceğim. Amacım, Ruby projelerinin AsciiDoc ve R'yi şu amaçlarla kullanabileceğini göstermektir:

• R kullanarak yeni hesaplamaları, algoritmaları vb. kolayca prototipleyin
• İşlevsel spesifikasyonunuzda ve diğer yazılı AsciiDoc belgelerinde R'den gelen sonuçları kolayca gösterin
• Belgelerin her zaman en son veriler ve algoritmalarla güncellenmesi için derleme sürecine bağlayın

İşlevsel bir özellik, API'nizi RDoc veya YARD ile belgelemenin yerini almaz; bir projedeki tüm paydaşlar (programcılar ve programcı olmayanlar) için referans olarak kullanılabilecek hayati bir eklemedir.

Prototip

Somon balıkçılığını severim ve hem kendim hem de başkaları için tuttukları balıkları takip edip ayrıntıları paylaşabilecekleri bir yol istiyorum. Ayrıca en iyi kullanıcıları sergilemek için bir puan tablosuna ihtiyacı var . Şu anda bu amaç için kullanılan forumlar var, ancak bir puan tablosu ile yapılandırılmış veriler çok daha havalı.

Ruby'de bir prototip yapabilirim ama Ruby grafik için en iyi desteğe sahip değil, bu yüzden R kullanacağım. R'yi kullanmak bana matematik ve görselleştirme ile oynamam için birçok kolay yol sağlıyor ve bu çapraz- platform.

 # Read in some example data data <- read.csv("func_spec/example_user_data.csv") # Compute the score, weighted by base-10 log of number of reports score <- mean(data$Fish.Caught) * log(length(data$Date)) / log(10)

Sadece iki satırda, bazı örnek verileri okudum ve tescilli puanımı kullanarak bir puan hesapladım. R bunu yapabilir ve vanilya kurulumuyla bir arsa gösterebilir, Ruby veya Python gibi diller daha fazla kod ve ek paketlerin yüklenmesini gerektirir.

Algoritmayı Belgelemek

Puanlama sistemimi yaptıktan sonra doğrudan kodlamaya geçebilirim. Aslında, R'de prototip oluşturmayı atlayabilir ve doğrudan Ruby on Rails uygulamamda prototip oluşturabilirdim. Bununla birlikte, R'deki prototipleme hızlıydı ve temeldeki matematiğe çok yakındı. Belgeleri şu şekilde ayarlayacağım:

• kingfisher/
  • Rakefile
  • doc/
    • func_spec.Radoc

Örnek Rails projemin adı yalıçapkını ve belgeleri bir “doc” klasörüne koyuyorum. Asciidoctor sitesi bunun için bir sürü harika belgeye sahip olduğundan AsciiDoc sözdizimini ele almayacağım, ancak AsciiDoc'a knitr ile bir grafiği nasıl yapıştıracağınız aşağıda açıklanmıştır:

 //begin.rcode freq_change, fig.asp=0.618, fig.width=12, fig.align="center" times_fished <- 1:50 plot(times_fished, 5 * log(times_fished) / log(10), ylab="User score when average 5 catches per trip", xlab="Number of fishing trips in the past 12 months") //end.rcode

Bunu func_spec.Radoc içine yapıştırın, knitr ve AsciiDoc'u çalıştırın ve belgelerinizde şöyle bir şey elde edeceksiniz:

Umarım çoğu geliştirici, skorun avlanma sayısıyla logaritmik olarak artacağını sezgisel olarak anlar; öyle olsa bile, emin olmak için bunu göstermenin harika bir yolu. Bu çizelgenin etrafında, balık tutmayan geliştiricilerin burada neler olduğunu anlayabilmeleri için bunun neden arzu edilir olduğunu açıklayan bir metnim olurdu. Bu örnek uydurmadır, ancak bu tür prototipleme ve dokümantasyonu geçmişte hesaplama sonuçlarının her zaman açık olmayabileceği diğer projeler (örneğin finans, inşaat tahmini) için kullandım.

Artık puanın prototipi oluşturulduğuna ve belgelere yapıştırılacak bir planımız olduğuna göre, geriye kalan tek şey AsciiDoc girdisini bir tür çıktı formatına dönüştürmek. HTML'ye dönüştürmek için Rakefile dosyamda birkaç kural kullanıyorum:

 require 'asciidoctor' require 'pathname' task docs: %w[doc/func_spec.html] rule '.adoc' => '.Radoc' do |t| Dir.chdir(Pathname.new(t.name).dirname) do sh "R -e 'library(knitr);knit(\"#{Pathname.new(t.source).basename}\", " + "\"#{Pathname.new(t.name).basename}\")'" end end rule '.html' => '.adoc' do |t| Dir.chdir(Pathname.new(t.name).dirname) do Asciidoctor.convert_file Pathname.new(t.source).basename, backend: :html5, to_file: true, safe: :safe end end

Artık "rake docs" çalıştırabilir ve temeldeki verileri veya puanlama hesaplamasını değiştirsem bile oluşturulacak ve her zaman güncel olacak belgeleri alabilirim.

Diğer Çözümler

Ruby on Rails ile ilgili her şey için, belgelerde özel grafikler olsun ya da olmasın AsciiDoc ile belgelemek harika bir seçimdir. AsciiDoc size harika bir biçimlendirme biçiminde yazmanız için Ruby'ye özgü bir yol sunar. Bununla birlikte, bir Rails projesi için oluşturma sürecinizi yönetmek ve bunlara bağlanmak için biraz daha fazla olacak başka harika dokümantasyon araçları da var.

Sphinx, reStructuredText'i (ayrıca güzel bir biçimlendirme formatı) işler ve Matplotlib'den çıktıları içerebilir. Bir Python projesi için bu mükemmel –Sphinx + Matplotlib size özel grafiklerle güzel belgeler üretmeniz için Python'a özgü bir yol sunar. Ancak, bir Rails projesi üzerinde çalışıyorsanız, yalnızca belgelerinizi oluşturmak için ayrı bir ortam için birden çok bağımlılık kümesini yönetmeniz pek de arzu edilen bir şey değildir.

Doxygen ve LaTeX gibi, yapı sisteminize uyması için daha fazla veya daha az yapıştırıcı gerektirebilecek programlar da dahil olmak üzere, belge üretmek için tonlarca başka çözüm vardır. LaTeX gibi bir sisteme ihtiyacınız varsa kullanın; oldukça standart bir Rails projeniz varsa ve belgelenmesi gereken biraz matematiğe sahipseniz, AsciiDoc ve R kullanın.

Çözüm

Ruby ve AsciiDoc harika bir ekip oluşturuyor ve belgelerinize güzel görselleştirmeler yapmak için R'yi karışıma dahil etmek çok kolay. Belgelerinizde güzel grafikler elde etmek için ggplot2 gibi R ekosistemindeki herhangi bir paketi atabilirsiniz.

Bu gönderi için kaynak materyal GitHub deposunda bulunabilir. Yayınlandığı gibi, bu depo “gerçek” bir projeye sahip değil, ancak gelecekte olabilir!

Ruby ile bir adım daha ileri gitmek istiyorsanız, Ruby ile Metaprogramming'i öğrenmenizi tavsiye ederim