Julia 相当于 R 的帮助页面和小插曲？

Question

我有 R 背景，刚开始学习 Julia，我想知道 Julia 中的文档如何，以及是否有与 R 的帮助页面和插图类似的内容。

此外，在 R 中，可以使用 roxygen 注释 block 来记录函数，Julia 中是否也有类似的东西？

Answer 1

我认为最好通过示例来理解事物的工作原理。我将评论如何记录 DataFrames.jl，因为这是一种非常标准的方法:

1. 函数使用文档字符串记录，here是函数 names 的文档字符串示例；然后可以通过帮助系统以交互方式发现这些文档字符串(通过按 ?)
2. 为包生成文档的标准方法是使用 Documenter.jl ;顺便说一下:这个包有一个很棒的维护者团队，他们非常乐于助人并且 react 迅速； here您有指向生成文档的 make.jl 文件的链接；特别注意选项 doctest=true，它确保所有按照 Documenter.jl 规则正确注释的代码示例都产生预期的输出
3. 为了设置自动生成包文档，您需要在 GitHub 上设置 CI 集成；再次-有很多方法可以做到；一个标准的方法是使用 GitHub Actions； here你有一个链接到 ci.yml 规范文件的一部分，确保文档是作为 CI 的一部分构建的；然后在任何 PR 中，例如this one (我提供了一个指向当前打开的与文档相关的 PR 的链接)您可以在报告 CI 结果的部分中看到，在运行测试后还生成了文档。 Here您可以看到使用此工具链生成的文档的样子(例如，请注意，在底部，您可以切换要动态阅读手册的软件包版本，这表明这里的所有内容都非常集成 - 而不仅仅是一堆PDF 或 HTML 文件)。

我希望这能帮助您入门。我已经向您指出了托管在 GitHub 上的包通常使用的所有基本部分(即这不是唯一的方法，但它是最常用的标准方法)。

要掌握上述所有细节，您需要仔细阅读 Julia Manual 和 Documenter.jl 中的文档。不幸的是，编写适当的文档并不容易(在任何编程语言中)。好消息是 Julia 有一个非常优秀的工具链，可以很好地支持这个过程。