Julia Documenter:缺少文档字符串

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

一个示例模块文件，

src/my_module.jl

，是：

module my_module

"""
    add(x, y)

Dummy function

# Examples
```jldoctest
julia> add(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
)

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

using Documenter, my_module

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

include（“src/my_module.jl”）

，然后

？

，然后

my_module.add

，显示Julia REPL找到了文档字符串：

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 REPL找到的是docstring而不是Documenter

---

注意：在运行代码之前，我运行了

Pkg.update（）

Documenter

的版本为

0.18.0

，Julia的版本为

0.6.3

，正如@fredrikekre的评论中提到的，我缺少

@autodocs

和一些其他细节。下面是使用

Documenter.jl

在

Julia

中进行文档测试的完整设置

my_模块的目录结构

（从命令树，为清晰起见重新排序）：

文件

src/my_module.jl

是：

using Documenter, my_module

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

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

using Documenter, my_module

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

文件

src/my_functions.jl

包含导出和未导出的函数。请注意，导出函数的文档测试没有限定条件，而非导出函数的文档测试有：

"""
    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",
    authors = "unknown",
    doctest = true
)

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

using Documenter, my_module

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

文件

docs/src/index.md

包含使用my_模块的

，该模块将导出的函数纳入范围：

# 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
包含标记中的描述：

# 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
更改为任何其他数字，则
文档管理员将显示一个错误并显示它正在工作。
您的
index.md
包含什么？我认为您的问题在于手册中没有包含文档字符串，即
@docs
块或
@autodocs
块中。请参阅手册：我还认为Documenter找不到未导出的名称。。。？至少没有默认设置？@George Datseris:默认情况下，包括导出和未导出的方法：“要仅包括模块中列出的模块中导出的名称，请使用Private=false。类似地，Public=false只能用于显示未报告的名称。默认情况下，这两个选项都设置为true，以便显示所有名称。链接。@fredrikekre:是的，我的
index.md
需要包含
@autodocs
。正如建议的那样，我还需要
@meta
index.md
现在有两个三重反引号的块：
@meta；CurrentModule=my_模块；DocTestSetup=quote；使用my_模块；结束
和
@autodocs；Modules=[my_module]
，其中冒号表示新行。我还需要导出测试中的函数，或者在其前面加上模块名。现在一切都好了。你想回答这个问题还是我应该回答？这是因为doctests是在沙盒模块中运行的，你需要添加
使用我的模块作为设置代码：@fredrikekre我在
docs/src/index.md
：
@meta中有一个设置代码；CurrentModule=my_模块；DocTestSetup=quote；导入myu模块；结束（其中分号表示新行）。你知道怎么回事吗？嗯，
import
只会将模块名带入范围。我建议
使用
，这会带来所有导出的名称，请看我的错误，我有
使用
而不是
导入
，我仍然得到文档测试错误
添加未定义
。你知道怎么回事吗？@fredrikekre你的评论指向了正确的方向：我需要导出要测试的函数，以便在没有条件的情况下使用它。谢谢