Ruby 相当于 Sphinx 文档生成器？答案

【问题标题】：Ruby equivalent of Sphinx documentation generator?Ruby 相当于 Sphinx 文档生成器？
【发布时间】：2012-03-11 10:42:47
【问题描述】：

Ruby 有一些不错的文档生成器，例如 Yard、rDoc，甚至 Glyph。问题是 Sphinx 做网站、PDF、epub、LaTex 等。它在重组文本中完成所有这些事情。

在 Ruby 世界中是否有替代方案？也许是程序的组合？如果我也可以使用 Markdown 那就更好了。

【问题讨论】：

用于文档或其他目的？
在 Sphinx 所做的一切中，http、pdf 和 epub 是我最感兴趣的。
目前尚不清楚您是在寻找一个可以实现 Sphinx 功能的工具，而是针对 Ruby 代码，还是在寻找专门用 Ruby 编写的工具。
我正在寻找一个用 Ruby 编写的工具
您的文档生成过程需要 ruby 的哪些方面？没有什么比 Ruby 中的 Sphinx 更像了，但我不清楚您通过使用不同语言的 Sphinx 的替代实现来解决什么问题。

标签： ruby markdown documentation-generation python-sphinx restructuredtext

【解决方案1】：

另外两个选项是使用 Middleman，它是一个静态站点生成器，可以接受 Kramdown 或 Markdown 作为输入。

还有专门为使用 Middleman 的技术文档设计的框架（两者都在 GitHub 上），包括 lord/slate 和 pnerger/dpslate（后者是前者的分支，并提供了一些不合适的增强功能用于拉动）。 Slate 格式提供了一种文档格式，其中包括 Sphinx 的许多功能以及一些额外的增强功能。它具有文档的三窗格视图，其中包括自动生成的目录、主要中心正文和右侧的示例代码面板。与 Sphinx 一样，示例代码具有语法高亮显示。

【讨论】：

【解决方案2】：

如果您想使用 Markdown，可以查看 JDoc，这是一个非常简单的基于 Ruby 的文档框架，可让您使用广泛支持的标记并将其置于源代码控制之下。它允许您在您选择的文本编辑器中编辑文档，并且它支持：

Markdown 或 Textile
语法高亮
简单的内部链接
分层文档结构（适用于大型项目）
可自定义的样式和结构（但开箱即用看起来也不错）

它生成静态 HTML，因此生成的文档易于托管，并且对您的服务器负载没有太大影响。

要查看它的实际效果，请查看wpmvc.org。

【讨论】：

【解决方案3】：

从 1.0 版开始，Sphinx 有了“域”的概念，它是从 Python 和/或 C 以外的语言标记代码实体（如方法调用、对象、函数等）的方式。

有一个ruby domain，所以你可以直接使用 Sphinx 本身。您唯一会缺少的（我认为）是 Sphinx 使用 autodoc 扩展自动从源代码创建文档的能力，该扩展专门适用于 Python 代码。

【讨论】：

那不是我真正想要的。我正在寻找一个用 Ruby 编写的工具，它可以做 Sphinx 可以做的事情。