1

我是一个相当大（并且还在增长）的框架的作者。它主要公开 JavaScript API，但也有 Ruby 中的公共 API 和不断增长的 CoffeeScript 部分。（CoffeeScript 最终将包含该项目的大部分内容，但总会有重要的纯 JavaScript 存在。）

到目前为止，我一直在用PDoc记录 JavaScript，用 RDoc 记录 Ruby。尽管我对 RDoc 没有任何意见，但不幸的是，PDoc 老化、维护成本高，并且需要大量打字，感觉像是多余的混乱。此外，将大部分代码转换为 CoffeeScript 会使 PDoc 的用处大大降低。

项目当前文档的示例

我在当地的一家分店对Rocco进行了试验，效果比我预期的要好。真正好的是它适用于我的所有代码，从 Ruby 到 Coffee 到 JS。很高兴在一个地方查看所有文档。在文档旁边看到源代码也很酷，这使得特定代码段实际上在做什么非常清楚。

但是，我有点担心整体结构。Docco/Rocco 似乎非常适合公共 API 很少的小众项目，但它的阅读整个项目风格让我觉得是一把双刃剑。虽然它提供的信息非常丰富，但必须在没有目录的情况下垂直滚动文件（更不用说，首先要知道要转到哪个文件！）似乎很难真正找到任何东西。此外，默认模板需要一些黑客攻击，因为文件列表太长而无法显示。没什么大不了的，但很烦人，并且暗示这个项目可能超出了 Rocco 的范围。

我现在正在考虑CoffeeDoc。仅从示例来看，它似乎很有希望，但它当然是以 Coffee 为中心的，这让我回到了运行 3 个单独的文档工具：RDoc、CoffeeDoc 和 -- 什么？JSDoc?

我并不完全反对为单独的源运行单独的工具，但是很难将其调和成一个连贯的结果，感觉不像是 3 个单独的网站。

所以我想我的问题是：你使用或建议什么工具？它支持什么语言？浏览、阅读和实际在大海捞针是您的项目是否容易？在这一点上，我什至考虑推出我自己的工具，但我不敢相信没有其他人遇到过这样的问题（如果我不需要的话，我真的不想浪费时间）。

4

1 回答 1

1

Sphinx直接支持javascript。通过扩展 ( https://bitbucket.org/birkenfeld/sphinx-contrib/ ) 支持 Ruby 和 CoffeeScript 的文档。

从网站：

存在以下功能，工作正常，可以在 Python 文档中看到“正在运行”：

  • 输出格式：HTML（包括 Windows HTML 帮助）、LaTeX（用于可打印的 PDF 版本）、手册页、纯文本
  • 广泛的交叉引用：语义标记和函数、类、引文、词汇表术语和类似信息的自动链接
  • 层次结构：文档树的简单定义，自动链接到兄弟姐妹、父母和孩子
  • 自动索引：通用索引以及模块索引
  • 代码处理：使用 Pygments 荧光笔自动高亮显示
  • 扩展：自动测试代码片段，包含来自 Python 模块的文档字符串（API 文档）等等
于 2012-05-14T22:08:12.120 回答