开发工具 SDoc - 帮你生成像 api.rubyonrails.org 那样的文档

huacnlee · 2017年03月03日 · 最后由 teddy_1004 回复于 2017年03月04日 · 4313 次阅读

我一直觉得 Ruby 社区最好的 API 文档,或者可以说我见过所有语言框架的 API 中最好的。查询方便,清晰。

我们都知道 Ruby 社区有 RDoc, Yardoc 两种工具可以基于源代码生成文档。

  • RDoc 是 Ruby 自带的工具,排版和交互比较差,Ruby 官方文档似乎就是它做的
  • Yardoc 要更好看一些,还有在线工具 http://rdoc.info/,但依然有些地方不是太好用,例如搜索,目录索引什么的

SDoc 另外一个选择

你可以用它轻松生成像 api.rubyonrails.org 那样的文档。

只需要 Gemfile 增加:

gem 'sdoc'
# 注意 Ruby 2.4 用
gem 'sdoc', '1.0.0.rc1'

然后 bundle install

修改 Rakefile

RDoc::Task.new do |rdoc|
  rdoc.rdoc_dir = 'public/rdoc'
  rdoc.generator = 'sdoc'
  rdoc.template = 'rails'
  rdoc.main = 'README.md'
  rdoc.rdoc_files.include("REAME.md", "API.md", "lib/", 'app/")
end

然后执行 rails rerdoc 就可以生成了,文档将会到 public/rdoc 目录。

SDoc 项目地址

https://github.com/zzak/sdoc

是的,Rails 的文档就是用它做的

Elixir 的文档也很好:

  1. 文档是 first-class
  2. 文档是 Markdown 格式的,人人都会写
  3. 文档里的 Example 代码还能当做测试来跑
  4. 官方支持本地生成和上传,比如 https://hexdocs.pm/plug/Plug.Builder.html#content

rdoc.rdoc_files.include("REAME.md", "API.md", "lib/", 'app/") REAME.md => README.md 少了个 D?

tony612 回复

先知道什么是好文档,再说什么是最好 :troll:

需要 登录 后方可回复, 如果你还没有账号请 注册新账号