Julia Documenter:缺少文档字符串 [英] Julia Documenter: missing docstring

问题描述

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

I have a Julia module file with a function, a doc-string, and a doc-test. I load it and the doc-string shows in the Julia help, but Documenter.jl cannot find the doc-string.

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

An example module file, src/my_module.jl, is:

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 是:

The make file docs/make.jl is:

using Documenter, my_module

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

include("src/my_module.jl") 的输出，然后是 ?，然后是 my_module.add，表明 JuliaREPL 找到了文档字符串:

The ouptut of include("src/my_module.jl"), then ?, then my_module.add, shows that the Julia REPL found the docstring:

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

  Dummy function

     Examples
    ≡≡≡≡≡≡≡≡≡≡

  julia> add(1, 2)
  3

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

The output of include("docs/make.jl") shows that Documenter did not:

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 怎么会找到文档字符串而不是 Documenter?

How come the Julia REPL finds the docstring and not Documenter?

注释:我在运行代码之前运行了 Pkg.update().Documenter 的版本是 0.18.0，Julia 的版本是 0.6.3.

Notes: I ran Pkg.update() before running the code. Documenter has version 0.18.0, Julia has version 0.6.3.

推荐答案

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

As mentioned in the comments of @fredrikekre, I was missing @autodocs and some other details. Here is a complete setup for doc-testing in Julia with Documenter.jl.

my_module 的目录结构(来自命令 tree，为清晰起见重新排序):

Directory structure of my_module (from command tree, reordered for clarity):

.
|____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 有:

The file src/my_functions.jl contains exported and non-exported functions. Note how the doc-test of exported functions has no qualification, and the doc-test of non-exported functions does:

"""
    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，它将导出的函数引入范围:

The file docs/src/index.md contains using my_module, which brings exported functions into scope:

# Documentation

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

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

最后两个文件是可选的.REQUIRE 文件仅用于远程安装包.它包含:

The last two files are optional. The file REQUIRE serves only for remote installation of package. It contains:

julia 0.6.3
DataFrames 0.11.6

文件 README.md 包含 Markdown 中的描述:

The file README.md contains a description in Markdown:

# my_module and its description

最后，将目录切换到包的根目录，启动 Julia 会话，然后输入:

Finally, change directory to the root of the package, start a Julia session, and type:

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.

如果您将 doc-test 中 add 的结果从 3 更改为任何其他数字，Documenter 将显示错误并表明它正在工作.

If you change the result of add in the doc-test from 3 to any other number, the Documenter will show an error and show that it is working.

这篇关于Julia Documenter:缺少文档字符串的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！