เอกสารอัลกอริทึม Ruby Algorithm ด้วย AsciiDoc และ Knitr

ทุกโปรเจ็กต์ที่ไม่สำคัญต้องมีเอกสารประกอบ และต้องมีคำอธิบายประกอบที่ดี หรือแม้แต่ภาพประกอบ เพื่อให้อ่านและนำไปใช้จริง วิศวกรสร้างซอฟต์แวร์ขึ้นมาเพื่อแก้ปัญหาทางธุรกิจ โดยทั่วไปแล้วไม่มีประสบการณ์กว้างขวางในธุรกิจนั้น ดังนั้นการบันทึกธุรกิจจึงมีความสำคัญพอๆ กับการบันทึกซอฟต์แวร์

เอกสารสามารถยึดติดได้หลังจากข้อเท็จจริง แต่ฉันพบว่าการเขียนข้อกำหนดการใช้งานก่อนการเข้ารหัสนั้นช่วยได้มาก ข้อมูลจำเพาะด้านการใช้งานเป็นที่มาของความจริงสำหรับสมาชิกทุกคนในทีมจากทุกสาขาวิชา และบังคับให้มีการออกแบบระดับสูงก่อนนำไปใช้จริง เพื่อป้องกันความพยายามที่สูญเปล่า ในโพสต์นี้ ฉันจะพูดถึงโปรเจ็กต์ตัวอย่างตั้งแต่การสร้างต้นแบบไปจนถึงการเขียนคุณสมบัติการใช้งานสำหรับตัวอย่างโปรเจ็กต์ Ruby on Rails เพื่ออธิบายว่าแอปควรทำอะไรและเป็นข้อมูลอ้างอิงระหว่างการพัฒนา เป้าหมายของฉันคือการแสดงให้เห็นว่าโปรเจ็กต์ Ruby สามารถใช้ AsciiDoc และ R เพื่อ:

• สร้างต้นแบบการคำนวณ อัลกอริธึม และอื่นๆ อย่างง่ายดายโดยใช้ R
• แสดงผลจาก R อย่างง่ายดายในคุณสมบัติการทำงานของคุณและเอกสารประกอบ AsciiDoc อื่น ๆ ที่เป็นลายลักษณ์อักษร
• เชื่อมโยงเข้ากับกระบวนการสร้างเพื่อให้เอกสารได้รับการอัปเดตด้วยข้อมูลและอัลกอริธึมล่าสุดเสมอ

ข้อมูลจำเพาะเชิงฟังก์ชันไม่ได้มาแทนที่การบันทึก API ของคุณด้วย RDoc หรือ YARD ซึ่งเป็นส่วนเสริมที่สำคัญที่สามารถใช้เป็นข้อมูลอ้างอิงสำหรับผู้มีส่วนได้ส่วนเสียทั้งหมด (โปรแกรมเมอร์และไม่ใช่โปรแกรมเมอร์) ในโครงการ

ต้นแบบ

ฉันชอบตกปลาแซลมอน และฉันต้องการวิธีสำหรับตัวเองและคนอื่นๆ ในการติดตามและแบ่งปันรายละเอียดเกี่ยวกับปลาที่พวกเขาจับได้ นอกจากนี้ยัง ต้อง มีป้ายบอกคะแนนเพื่อแสดงผู้ใช้อันดับต้นๆ ขณะนี้มีฟอรัมที่ใช้เพื่อจุดประสงค์นี้ แต่ข้อมูลที่มีโครงสร้างพร้อมกระดานคะแนนนั้นเจ๋งกว่า

ฉันสามารถสร้างต้นแบบใน Ruby ได้ แต่ Ruby ไม่มีการสนับสนุนที่ดีที่สุดสำหรับการสร้างกราฟ ดังนั้นฉันจะใช้ R การใช้ R ทำให้ฉันมีวิธีง่ายๆ มากมายในการเล่นกับคณิตศาสตร์และการแสดงภาพ และมันก็เป็นการข้าม แพลตฟอร์ม.

 # 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)

ในเวลาเพียงสองบรรทัด ฉันอ่านข้อมูลตัวอย่างและคำนวณคะแนนโดยใช้คะแนนที่เป็นกรรมสิทธิ์ของฉัน R สามารถทำได้และแสดงพล็อตด้วยการติดตั้งวานิลลา ในขณะที่ภาษาอย่าง Ruby หรือ Python จะต้องติดตั้งโค้ดและแพ็คเกจเพิ่มเติมเพิ่มเติม

การจัดทำเอกสารอัลกอริทึม

หลังจากสร้างระบบการให้คะแนนแล้ว ฉันก็ไปที่โค้ดได้เลย อันที่จริง ฉันสามารถข้ามการสร้างต้นแบบใน R และเพียงแค่สร้างต้นแบบโดยตรงในแอพ Ruby on Rails ของฉัน อย่างไรก็ตาม การสร้างต้นแบบใน R นั้นรวดเร็วและใกล้เคียงกับคณิตศาสตร์พื้นฐานมาก ฉันจะตั้งค่าเอกสารดังนี้:

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

ตัวอย่างโครงการ Rails ของฉันเรียกว่า Kingfisher และฉันกำลังใส่เอกสารประกอบลงในโฟลเดอร์ "doc" ฉันจะไม่ข้ามไวยากรณ์ AsciiDoc เนื่องจากไซต์ Asciidoctor มีเอกสารมากมายสำหรับสิ่งนั้น แต่นี่คือวิธีการติดแผนภูมิใน AsciiDoc ด้วย 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

ติดที่ func_spec.Radoc เรียกใช้ knitr และ AsciiDoc แล้วคุณจะได้สิ่งนี้ในเอกสารของคุณ:

หวังว่านักพัฒนาส่วนใหญ่จะเข้าใจโดยสัญชาตญาณว่าคะแนนจะเพิ่มขึ้นแบบลอการิทึมด้วยจำนวนครั้งที่ตกปลาได้ ถึงกระนั้น นี่เป็นวิธีที่ดีในการแสดงผลเพื่อให้แน่ใจว่า รอบๆ แผนภูมินี้ ฉันมีข้อความที่อธิบายว่าเหตุใดจึงเป็นที่ต้องการ เพื่อให้นักพัฒนาที่ไม่ตกปลาสามารถเข้าใจได้ว่าเกิดอะไรขึ้นที่นี่ ตัวอย่างนี้มีการวางแผน แต่ฉันเคยใช้การสร้างต้นแบบและเอกสารประเภทนี้มาก่อนสำหรับโครงการอื่นๆ (เช่น การเงิน การประมาณการก่อสร้าง) ซึ่งผลลัพธ์ของการคำนวณอาจไม่ชัดเจนเสมอไป

ตอนนี้คะแนนถูกสร้างเป็นต้นแบบแล้ว และเรามีโครงเรื่องที่จะติดอยู่ในเอกสารประกอบ ที่เหลือก็แค่แปลงอินพุต AsciiDoc ให้เป็นรูปแบบเอาต์พุตบางประเภท ฉันใช้กฎสองสามข้อใน Rakefile เพื่อแปลงเป็น 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

ตอนนี้ ฉันสามารถเรียกใช้ "rake docs" และรับเอกสารเพื่อสร้างและอัปเดตอยู่เสมอ แม้ว่าฉันจะเปลี่ยนข้อมูลพื้นฐานหรือการคำนวณคะแนน

โซลูชั่นอื่นๆ

สำหรับทุกสิ่งที่เกี่ยวข้องกับ Ruby on Rails การบันทึกด้วย AsciiDoc เป็นตัวเลือกที่ดีไม่ว่าจะมีกราฟิกแบบกำหนดเองในเอกสารหรือไม่ AsciiDoc ช่วยให้คุณเขียน Ruby-native ในรูปแบบมาร์กอัปที่ยอดเยี่ยม ที่กล่าวว่ามีเครื่องมือเอกสารที่ยอดเยี่ยมอื่น ๆ อีกเล็กน้อยที่จะจัดการและเชื่อมโยงกับกระบวนการสร้างของคุณสำหรับโครงการ Rails ได้อีกเล็กน้อย

สฟิงซ์ประมวลผลข้อความที่ปรับโครงสร้างใหม่ (ยังเป็นรูปแบบมาร์กอัปที่ดี) และสามารถรวมเอาท์พุตจาก Matplotlib ได้ สำหรับโปรเจ็กต์ Python นี่เป็นวิธีที่สมบูรณ์แบบ – Sphinx + Matplotlib ให้วิธี Python ดั้งเดิมแก่คุณในการสร้างเอกสารที่ดีพร้อมกราฟิกที่กำหนดเอง อย่างไรก็ตาม หากคุณกำลังทำงานในโปรเจ็กต์ Rails การจัดการการขึ้นต่อกันหลายชุดสำหรับสภาพแวดล้อมที่แยกจากกัน ก็ไม่ควรทำอย่างยิ่งยวดเพื่อจัดทำเอกสารของคุณ

มีโซลูชันอื่นๆ มากมายสำหรับการผลิตเอกสารประกอบ รวมถึงโปรแกรมอย่าง doxygen และ LaTeX ซึ่งอาจต้องใช้กาวมากหรือน้อยเพื่อให้พอดีกับระบบงานสร้างของคุณ หากคุณต้องการระบบอย่าง LaTeX ให้ใช้ระบบนั้น หากคุณมีโปรเจ็กต์ Rails ที่ค่อนข้างเป็นมาตรฐาน และคุณมีคณิตศาสตร์เพียงเล็กน้อยที่ควรจัดทำเป็นเอกสาร ให้ใช้ AsciiDoc และ R

บทสรุป

Ruby และ AsciiDoc สร้างทีมที่ยอดเยี่ยม และง่ายต่อการรวม R ไว้ในมิกซ์เพื่อสร้างภาพที่สวยงามในเอกสารของคุณ คุณสามารถใส่แพ็คเกจใดก็ได้ในระบบนิเวศ R เช่น ggplot2 เพื่อรับแผนภูมิที่สวยงามในเอกสารของคุณ

แหล่งข้อมูลสำหรับโพสต์นี้สามารถพบได้ที่ repo GitHub เมื่อมีการตีพิมพ์ repo นั้นไม่มีโครงการ "ของจริง" แต่อาจเป็นได้ในอนาคต!

หากคุณต้องการพูดคุยกับ Ruby ไปอีกขั้น ฉันแนะนำให้เรียนรู้ Metaprogramming ด้วย Ruby Metaprogramming นั้นเจ๋งกว่า ที่คิด