Dokumentasi Algoritma Ruby dengan AsciiDoc dan Knitr

Setiap proyek non-sepele membutuhkan dokumentasi, dan perlu melibatkan penjelasan yang bagus, dan bahkan ilustrasi, sehingga benar-benar dibaca dan digunakan. Insinyur membuat perangkat lunak untuk memecahkan masalah bisnis, umumnya tanpa memiliki pengalaman yang luas dalam bisnis tertentu, sehingga mendokumentasikan bisnis sama pentingnya dengan mendokumentasikan perangkat lunak.

Dokumentasi dapat dibaut setelah fakta, tetapi saya menemukan bahwa menulis spesifikasi fungsional sebelum pengkodean sangat membantu. Spesifikasi fungsional adalah sumber kebenaran bagi setiap anggota tim lintas disiplin, dan memaksa desain tingkat tinggi sebelum implementasi, mencegah upaya yang sia-sia. Dalam posting ini, saya akan membahas proyek contoh dari membuat prototipe hingga menulis spesifikasi fungsional untuk contoh proyek Ruby on Rails untuk menjelaskan apa yang seharusnya dilakukan aplikasi dan menjadi referensi selama pengembangan. Tujuan saya adalah untuk menunjukkan bahwa proyek Ruby dapat menggunakan AsciiDoc dan R untuk:

• Membuat prototipe kalkulasi baru, algoritme, dll. dengan mudah menggunakan R
• Menampilkan hasil dari R dengan mudah dalam spesifikasi fungsional Anda dan dokumentasi AsciiDoc tertulis lainnya
• Ikat ke dalam proses pembuatan sehingga dokumentasi selalu diperbarui dengan data dan algoritme terbaru

Spesifikasi fungsional bukanlah pengganti untuk mendokumentasikan API Anda dengan RDoc atau YARD–ini adalah tambahan penting yang dapat digunakan sebagai referensi bagi semua pemangku kepentingan (programmer dan non-programmer) dalam sebuah proyek.

Prototipe

Saya suka memancing salmon, dan saya ingin cara bagi saya dan orang lain untuk melacak dan berbagi detail tentang ikan yang mereka tangkap. Itu juga membutuhkan papan skor untuk menampilkan pengguna teratas. Saat ini ada forum yang digunakan untuk tujuan ini, tetapi data terstruktur dengan papan skor jauh lebih keren.

Saya bisa membuat prototipe di Ruby, tetapi Ruby tidak memiliki dukungan terbaik untuk grafik, jadi saya akan menggunakan R. Menggunakan R memberi saya banyak cara mudah untuk bermain dengan matematika dan visualisasi, dan itu lintas- 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)

Hanya dalam dua baris, saya membaca beberapa contoh data dan menghitung skor menggunakan skor milik saya. R dapat melakukan ini dan menampilkan plot dengan instalasi vanilla, sementara bahasa seperti Ruby atau Python akan membutuhkan lebih banyak kode dan paket tambahan untuk diinstal.

Mendokumentasikan Algoritma

Setelah membuat sistem penilaian saya, saya bisa langsung ke kode. Sebenarnya, saya bisa melewatkan pembuatan prototipe di R dan hanya membuat prototipe langsung di aplikasi Ruby on Rails saya. Namun, pembuatan prototipe dalam R cepat dan sangat dekat dengan matematika yang mendasarinya. Berikut cara saya menyiapkan dokumentasi:

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

Contoh proyek Rails saya disebut kingfisher, dan saya memasukkan dokumentasi ke dalam folder "doc". Saya tidak akan membahas sintaks AsciiDoc karena situs Asciidoctor memiliki banyak dokumentasi bagus untuk itu, tetapi berikut ini cara menempelkan bagan ke AsciiDoc dengan knitr:

 //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

Tempelkan itu ke func_spec.Radoc , jalankan knitr dan AsciiDoc, dan Anda akan mendapatkan sesuatu seperti ini di dokumentasi Anda:

Mudah-mudahan sebagian besar pengembang secara intuitif memahami skor akan naik secara logaritmik dengan berapa kali memancing; meski begitu, ini adalah cara yang bagus untuk menampilkannya hanya untuk memastikan. Di sekitar bagan ini, saya memiliki beberapa teks yang menjelaskan mengapa ini diinginkan sehingga pengembang yang tidak memancing dapat memahami apa yang terjadi di sini. Contoh ini dibuat-buat, tetapi saya telah menggunakan jenis prototipe dan dokumentasi ini di masa lalu untuk proyek lain (misalnya keuangan, perkiraan konstruksi) di mana hasil perhitungan mungkin tidak selalu jelas.

Sekarang skor sudah diprototipe dan kami memiliki plot untuk ditempel di dokumentasi, yang tersisa hanyalah mengubah input AsciiDoc menjadi semacam format output. Saya menggunakan beberapa aturan di Rakefile saya untuk mengubah ke HTML:

 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

Sekarang saya dapat menjalankan "rake docs" dan mendapatkan dokumentasi untuk dibuat dan selalu up to date, bahkan jika saya mengubah data yang mendasari atau perhitungan penilaian.

Solusi lain

Untuk apa pun yang melibatkan Ruby on Rails, mendokumentasikan dengan AsciiDoc adalah pilihan tepat apakah ada grafik khusus dalam dokumentasi atau tidak. AsciiDoc memberi Anda cara asli Ruby untuk menulis dalam format markup yang bagus. Karena itu, ada alat dokumentasi hebat lainnya yang akan sedikit lebih banyak untuk dikelola dan diikat ke dalam proses pembuatan Anda untuk proyek Rails.

Sphinx memproses reStructuredText (juga format markup yang bagus) dan dapat menggabungkan output dari Matplotlib. Untuk proyek Python, ini sempurna–Sphinx + Matplotlib memberi Anda cara asli Python untuk menghasilkan dokumentasi yang bagus dengan grafik khusus. Namun, jika Anda sedang mengerjakan proyek Rails, mengelola beberapa set dependensi untuk lingkungan terpisah hanya untuk menghasilkan dokumentasi Anda bukanlah hal yang diinginkan.

Ada banyak solusi lain untuk membuat dokumentasi, termasuk program seperti doxygen dan LaTeX, yang mungkin memerlukan lebih banyak atau lebih sedikit lem agar sesuai dengan sistem build Anda. Jika Anda membutuhkan sistem seperti LaTeX, gunakan itu; jika Anda memiliki proyek Rails yang cukup standar dan Anda hanya memiliki sedikit matematika yang harus didokumentasikan, gunakan AsciiDoc dan R.

Kesimpulan

Ruby dan AsciiDoc menjadi tim yang hebat, dan mudah untuk memasukkan R ke dalam campuran untuk membuat visualisasi yang bagus dalam dokumentasi Anda. Anda dapat memasukkan paket apa pun di ekosistem R, seperti ggplot2, untuk mendapatkan bagan yang indah dalam dokumentasi Anda.

Materi sumber untuk posting ini dapat ditemukan di repo GitHub-nya. Pada publikasi, repo itu tidak memiliki proyek "nyata", tetapi mungkin di masa depan!

Jika Anda ingin berbicara lebih jauh dengan Ruby, saya sarankan belajar Metaprogramming dengan Ruby Metaprogramming Bahkan Lebih Keren Dari Kedengarannya .