Юлия Документатор: отсутствует документация - PullRequest
Новая
       6

Юлия Документатор: отсутствует документация

0 голосов
/ 08 июня 2018

У меня есть файл модуля 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
)

Выход 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 находит строку документации, а не Documenter?

Примечания : Я запустил Pkg.update() перед запуском кода.Documenter имеет версию 0.18.0, Джулия имеет версию 0.6.3.

1 Ответ

0 голосов
/ 06 июля 2018

Как уже упоминалось в комментариях @fredrikekre, мне не хватало @autodocs и некоторых других деталей.Вот полная настройка для doc-тестирования в 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 = 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 в doc-тесте с 3 на любое другое число, Documenter отобразит ошибку и покажет, что она работает.

...