Julia Documenter:缺少docstring

Question

我有一个带函数、文档字符串和文档测试的Julia模块文件。我加载它，文件字符串显示在Julia中，但是Documenter.jl找不到文档字符串。

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

module my_module

"""
    add(x, y)

Dummy function

# Examples
```jldoctest

julia>添加(1，2)

3.

"""
function add(x::Number, y::Number)
    return x + y
end

end

make文件docs/make.jl是：

using Documenter, my_module

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

include("src/my_module.jl")的ouptut，然后是?，然后是my_module.add，显示Julia找到了docstring：

help?> my_module.add
  add(x, y)

  Dummy function

     Examples
    ≡≡≡≡≡≡≡≡≡≡

  julia> add(1, 2)
  3

include("docs/make.jl")的输出表明，Documenter没有：

Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
 > checking for missing docstrings.
 !! 1 docstring potentially missing:

    my_module.add :: Tuple{Number,Number}

 > running doctests.
 > checking footnote links.
Documenter: populating indices.
Documenter: rendering document.

为什么Julia会找到文档字符串而不是文档记录呢？

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

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测试是如何没有资格的，对非导出函数的doc测试是如何做到的：

"""
    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 =报价

using my_module

结束

```@autodocs

模块= 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将显示一个错误并显示其工作正常。