如何使用YARD记录Rake任务？

Question

我希望在我们的Rails应用程序中包含关于Rake任务的信息。我们使用YARD进行文档编写，但目前像lib/tasks/development.rake这样的页面默认显示为未格式化文本。

我可以使用来自YARD文档的# @markup ruby将它们呈现为Ruby源代码。

然而，这只是将任何注释作为内联呈现，即使它们包括像# @!method foo这样的YARD指令。这意味着关于标记DSL的YARD文档似乎不适用。

我是否漏掉了什么？

我如何让YARD识别.rake文件中的代码与文档？

注意：我将接受忽略实际代码但生成文档副本的解决方案，但文档副本的源必须是.rake文件本身 - 我不想将文档放在单独的.markdown文件中（或其他任何文件），因为这样会有太多的不同步机会。

更多信息——yard命令：

我正在使用一个包含以下内容的.yardopts文件：

--asset graphs 'app/**/*.rb' 'lib/**/*.rb' - README info/*

为了让YARD阅读Rake任务，我可以在连字符后添加'lib/tasks/*.rake'（即将Rake文件添加到YARD的“文件”列表中），但正如上面所述，这样不会正确处理它们。

根据Benjamin的建议，我尝试在连字符之前添加'lib/tasks/*.rake'（即将Rake文件添加到要处理的常规Ruby文件列表中），但似乎没有生成任何内容。

可能是YARD正在生成某些内容，但并非在预期位置/使用预期的文件名，我想，我不熟悉YARD的工作方式，也无法确定是否存在孤立的输出。肯定没有适当的内容出现在YARD生成的搜索结果中，简单的find doc | grep rake或find doc | grep basename_of_rake_file也没有显示任何内容。

- Leo

---

这只是让Yard识别*.rake文件为Ruby的问题吗？ - ipd

很抱歉自从提问后我没有仔细研究过这个问题，但我想基本上是这样的。然而，实际上使用 # @markup ruby 指令来指定它们是 Ruby 并不起作用，因为它只呈现 Ruby 代码，也就是说，它不再处理文档注释。 - Leo

@Leo，命令行上指定rake扩展名有帮助吗？yardoc *.rake -o out/? - benjamin

...或者使用“_AT note_”标签？ - benjamin

@benjamin 刚刚试了一下，恐怕似乎不起作用。将 lib/tasks/*.rake 添加到 yardoc 命令的 files 部分可以使其工作，但然后它只能将它们读作文本（如问题所述）。将它们添加到命令正文中似乎根本没有为这些文件生成任何内容，即 Yard 类/方法/文件列表中未列出任何内容，并且输出 doc/ 目录中似乎没有任何内容。我应该在哪里寻找输出呢？ - Leo

我已经在使用的 YARD 选项上添加了更多细节... - Leo

Answer 1

来自YARD文档：

在使用YARD生成文档的入门指南部分中，查看文档化额外文件或向额外文件添加元数据。这可能会有所帮助。

- BenJaminSila