แบ็คเอนด์

เอกสารอัลกอริทึม Ruby พร้อม 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 แล้วคุณจะได้รับสิ่งนี้ในเอกสารของคุณ:

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

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

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

สรุป

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

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

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

ทำความเข้าใจพื้นฐาน

AsciiDoc คืออะไร?

AsciiDoc เป็นรูปแบบมาร์กอัปที่คล้ายกับ Markdown และ reStructuredText ที่มีไว้สำหรับการเผยแพร่ในรูปแบบ HTML, PDF หรือรูปแบบอื่น ๆ

ข้อกำหนดการทำงานคืออะไร?

ข้อกำหนดเกี่ยวกับการทำงานคือเอกสารที่อธิบายถึงวิธีการทำงานของโครงการที่ผู้มีส่วนได้ส่วนเสียของโครงการทุกคนเข้าใจได้

ตัวอย่างของ AsciiDoc คืออะไร?

= ชื่อเอกสาร Alec Ten Harmsel นี่คือเนื้อหาของเอกสาร

ทำไมต้องเขียนข้อกำหนดการทำงาน

ข้อกำหนดด้านการใช้งานเป็นแหล่งที่มาของความจริงสำหรับสมาชิกทุกคนในทีมในทุกสาขาวิชาและบังคับให้มีการออกแบบระดับสูงก่อนการใช้งานเพื่อป้องกันการสูญเสียความพยายาม