Julia Documenter：缺少文档字符串

Question

我有一个 Julia 模块文件，其中包含一个函数、一个文档字符串和一个文档测试。我加载它并且文档字符串显示在 Julia 帮助中，但 Documenter.jl 找不到文档字符串。

\n\n

示例模块文件src/my_module.jl是：

\n\n

module my_module\n\n"""\n    add(x, y)\n\nDummy function\n\n# Examples\n```jldoctest\njulia> add(1, 2)\n3\n```\n"""\nfunction add(x::Number, y::Number)\n    return x + y\nend\n\nend\n

\n\n

制作文件docs/make.jl是：

\n\n

using Documenter, my_module\n\nmakedocs(\n    modules = [my_module],\n    format = :html,\n    sitename = "my_module.jl",\n    authors = "unknown",\n    doctest = true\n)\n

\n\n

include("src/my_module.jl")、 then ?、 then的输出my_module.add显示 Julia REPL 找到了文档字符串：

\n\n

help?> my_module.add\n  add(x, y)\n\n  Dummy function\n\n     Examples\n    \xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\xe2\x89\xa1\n\n  julia> add(1, 2)\n  3\n

\n\n

的输出include("docs/make.jl")显示Documenter没有：

\n\n

Documenter: setting up build directory.\nDocumenter: expanding markdown templates.\nDocumenter: building cross-references.\nDocumenter: running document checks.\n > checking for missing docstrings.\n !! 1 docstring potentially missing:\n\n    my_module.add :: Tuple{Number,Number}\n\n > running doctests.\n > checking footnote links.\nDocumenter: populating indices.\nDocumenter: rendering document.\n

\n\n

为什么 Julia REPL 找到了文档字符串而不是 Documenter？

\n\n

注意：我Pkg.update()在运行代码之前运行了。Documenter有版本0.18.0，朱莉娅有版本0.6.3。

\n

Answer 1

正如 @fredrikekre 的评论中提到的，我遗漏了@autodocs一些其他细节。Julia这是使用 进行文档测试的完整设置Documenter.jl。

目录结构my_module（来自命令tree，为了清晰起见重新排序）：

.
|____src
| |____my_module.jl
| |____my_functions.jl
|____docs
| |____make.jl
| |____src
| | |____index.md
|____README.md
|____REQUIRE

该文件src/my_module.jl是：

module my_module

# export functions you want to call without qualifications
export add_exported

using DataFrames # or any other module

# Include functions
include("my_functions.jl")

end

该文件src/my_functions.jl包含导出和非导出函数。请注意导出函数的 doc-test 没有限定条件，而非导出函数的 doc-test 则有：

"""
    add_exported(x, y)

Dummy function, exported

# Examples
```jldoctest
julia> add_exported(1, 2)
3
```
"""
function add_exported(x::Number, y::Number)
    return x + y
end

"""
    add_not_exported(x, y)

Dummy function, not exported

# Examples
```jldoctest
julia> my_module.add_not_exported(1, 2)
3
```
"""
function add_not_exported(x::Number, y::Number)
    return x + y
end

该文件docs/make.jl是：

using Documenter, my_module

makedocs(
    modules = [my_module],
    format = :html,
    sitename = "my_module.jl",
    doctest = true
)

该文件docs/src/index.md包含using my_module，它将导出的函数纳入范围：

# Documentation

```@meta
CurrentModule = my_module
DocTestSetup = quote
    using my_module
end
```

```@autodocs
Modules = [my_module]
```

最后两个文件是可选的。该文件REQUIRE仅用于软件包的远程安装。它包含了：

julia 0.6.3
DataFrames 0.11.6

该文件README.md包含 Markdown 格式的描述：

# my_module and its description

最后，将目录更改为包的根目录，启动 Julia 会话，然后输入：

julia> include("src/my_module.jl");include("docs/make.jl");
Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
 > checking for missing docstrings.
 > running doctests.
 > checking footnote links.
Documenter: populating indices.
Documenter: rendering document.

add如果您将文档测试中的结果更改为3任何其他数字，则会Documenter显示错误并表明它正在工作。