帶有 AsciiDoc 和 Knitr 的 Ruby 算法文檔

已發表: 2022-03-11

每個重要的項目都需要文檔，並且需要有很好的解釋，甚至是插圖，這樣才能真正被閱讀和使用。 工程師製作軟件是為了解決業務問題，通常在特定業務中沒有豐富的經驗，因此記錄業務與記錄軟件一樣重要。

事後可以添加文檔，但我發現在編碼之前編寫功能規範很有幫助。 功能規範是跨學科團隊中每個成員的真實來源，並在實施之前強制進行高級設計，防止浪費精力。 在這篇文章中，我將介紹一個示例項目，從原型設計到為示例 Ruby on Rails 項目編寫功能規範，以描述應用程序應該做什麼，並在開發過程中作為參考。 我的目標是展示 Ruby 項目可以使用 AsciiDoc 和 R 來：

  • 使用 R 輕鬆製作新計算、算法等的原型
  • 在您的功能規範和其他書面 AsciiDoc 文檔中輕鬆顯示 R 的結果
  • 將其與構建過程聯繫起來，以便始終使用最新數據和算法更新文檔

功能規範不能替代使用 RDoc 或 YARD 記錄 API ——它是一個重要的補充，可以用作項目中所有利益相關者（程序員和非程序員等）的參考。

原型

我喜歡釣鮭魚，我希望自己和其他人能夠跟踪並分享他們所捕獲的魚的詳細信息。 它還需要一個記分牌來展示頂級用戶。 現在有用於此目的的論壇，但帶有記分牌的結構化數據更酷。

我可以在 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 網站有很多很棒的文檔，但是這裡是如何使用 knitr 將圖表粘貼到 AsciiDoc 中的方法：

 //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 為您提供了一種 Ruby 原生的方式來編寫出色的標記格式。 也就是說，還有其他很棒的文檔工具可以更多地管理和綁定到 Rails 項目的構建過程中。

Sphinx 處理 reStructuredText（也是一種很好的標記格式）並且可以合併來自 Matplotlib 的輸出。 對於 Python 項目，這是完美的——Sphinx + Matplotlib 為您提供了一種 Python 原生的方式來生成帶有自定義圖形的漂亮文檔。 但是，如果您正在處理 Rails 項目，那麼為了生成文檔而必須為單獨的環境管理多組依賴項是不可取的。

還有很多其他的用於生成文檔的解決方案，包括像 doxygen 和 LaTeX 這樣的程序，它們可能需要或多或少的膠水來適應你的構建系統。 如果你需要像 LaTeX 這樣的系統，使用它； 如果您有一個相當標準的 Rails 項目，並且您只有一些應該記錄的數學，請使用 AsciiDoc 和 R。

結論

Ruby 和 AsciiDoc 組成了一個很棒的團隊，很容易將 R 混合在一起，在您的文檔中製作漂亮的可視化效果。 您可以放入 R 生態系統中的任何包，例如 ggplot2，以在您的文檔中獲得漂亮的圖表。

這篇文章的源材料可以在其 GitHub 存儲庫中找到。 截至發佈時，該 repo 並沒有一個“真正的”項目，但它可能在未來！

如果您想進一步了解 Ruby，我建議您學習使用Ruby 進行元編程 元編程比聽起來更酷。