带有AsciiDoc和Knitr的Ruby算法文档 _Knitr

本文概述

原型
记录算法
其他解决方案
总结

每个不平凡的项目都需要文档, 并且需要有丰富的解释, 甚至包括插图, 以便可以实际阅读和使用。工程师通常在没有特定业务经验的情况下开发软件来解决业务问题, 因此, 记录业务与记录软件一样重要。
事实发生后可以附加文档, 但是我发现在编码之前编写功能说明很有帮助。功能规范是跨学科的团队中每个成员的真理之源, 并在实施之前强制进行高级设计, 以防止浪费精力。在本文中, 我将遍历一个示例项目, 从原型设计到编写示例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中的原型制作速度很快, 并且非常接近基础数学。我将按照以下方式设置文档：

翠鸟/
- Rake文件
- 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, 你将在文档中得到以下内容：

文章图片
希望大多数开发人员凭直觉理解分数会与钓鱼次数成对数增长；即使这样, 这也是一种确保显示的好方法。在这张图表的周围, 我会有一些文字解释为什么这样做是理想的, 以便不钓鱼的开发人员可以了解这里的情况。这个示例是人为设计的, 但是我过去在其他项目(例如财务, 建筑估算)中使用了这种类型的原型设计和文档, 而这些项目的计算结果可能并不总是显而易见的。
现在已经完成了乐谱的原型制作, 并且我们可以在文档中添加一些内容, 剩下的就是将输入的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 endrule '.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仓库中找到。截至发布之日, 该回购协议并未包含” 真实” 项目, 但将来可能会存在！
【带有AsciiDoc和Knitr的Ruby算法文档】如果你想进一步了解Ruby, 我建议你学习使用Ruby元编程比听起来更酷的元编程。