23、近乎免费地获取文档

近乎免费地获取文档

1. 企业应用文档的重要性

开发企业应用成本高昂，很多应用会逐渐陈旧。这些应用通常由多代开发者维护，而良好的文档是实现这一点的关键。软件项目文档中最重要的部分是从程序源代码生成的 API 文档，以及描述应用所使用数据库结构的图表。这些部分也是最不稳定的，经常会发生变化。现代语言大多具备自动创建此类文档的机制，Ruby 也不例外。

2. 自动生成文档

2.1 问题描述

完成新的 Rails 应用后，要部署到生产环境，在此之前，QA 部门需要数据库图表展示应用模型之间的关系，以及解释所有类和方法的 API 文档。

2.2 所需工具

• 安装 Railroad，用于生成数据库图表：

$ gem install railroad

• 安装 Graphviz 工具套件，用于可视化图形，它是免费开源的。

2.3 示例数据库及模型

假设应用数据库包含典型的 COLA 表：customers、orders、line items 和 accounts，通过以下 ActiveRecord 迁移创建：

create_table :customers do |t|
  t.string :forename, :surname
  t.timestamps
end

create_table :accounts do |t|
  t.