additionnal documentation of julia make.jl for newbies

[reumle]

Hi I just used Documenter for the first time. Thanks all for the great stuff!
I initially struggled letting julia make work as i was trying to start documenting a package. I had errors such as

ERROR: LoadError: ArgumentError: Package Query not found in current path:
- Run `import Pkg; Pkg.add("Query")` to install the Query package.

Finally i found https://discourse.julialang.org/t/problem-using-documenter-jl/29052 . It solves my issue (with the first 2 lines of code below) . I suggest to incorporate the tip in the Documenter docs with something like this:

using Pkg
Pkg.activate("..")
push!(LOAD_PATH,"../src/")
using Documenter, MYPACKAGENAME

makedocs(sitename="My Documentation")

Except if it is already in the docs, but i could not find it.
Ok for a pull request to that effect?
Regards.

[mortenpi]

The beginner section of the docs should definitely be improved.

However, I don't really agree with this particular suggestions (putting various Pkg calls into make.jl). We generally assume that you just start Julia with julia --project=docs/. This does require some understanding of how Pkg environments work though (e.g. you need to make sure that your package has been added as a dev. dependency).

[reumle]

Hi Morten , Thank you for your feedback. My somewhat long answer below.

tldr: either the "beginner" instructions are not completely robust, or I am using them wrong (My bayesian opinion would point towards the second solution, the most likely outcome of beginners trying beginner instructions... 😃 ) , but maybe the information below would show otherwise?

1. I usually start julia from within vscode, so no --project=docs option.

2. the package I am trying to document is indeed declared as a dev dependency in another environment. But IIUC this is not visible to the julia make.jl instruction..

3. I reran the set of instructions from https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Package-Guide and it failed again.

FWIW, i am trying to ressuscitate (/spring cleaning) this package: https://github.com/mkriele/ValueOrientedRiskManagementInsurance.jl, which I downloaded and am modifying locally.

• first some info about my setup: make.jl , project.toml..

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance>cd docs

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs>dir
 Le volume dans le lecteur C s’appelle Windows
 Le numéro de série du volume est F62C-E199

 Répertoire de C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs

14/04/2021  23:26    <DIR>          .
14/04/2021  23:26    <DIR>          ..
14/04/2021  23:32               123 make.jl
14/04/2021  23:29    <DIR>          src
               1 fichier(s)              123 octets
               3 Rép(s)  110,076,059,648 octets libres

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs>more make.jl
push!(LOAD_PATH,"../src/")
using Documenter, ValueOrientedRiskManagementInsurance

makedocs(sitename="My Documentation")

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs>more ..\project.toml
name = "ValueOrientedRiskManagementInsurance"
uuid = "8c03090b-494f-4d55-b8bd-6cadd69a7233"
authors = ["reumle <jpojpoj@gmail.com> and contributors"]
version = "1.0.1"

[deps]
DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

[compat]
julia = "1"

[extras]
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]

• now the trial run of julia make.jl

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs>julia make.jl
ERROR: LoadError: ArgumentError: Package Distributions not found in current path:
- Run `import Pkg; Pkg.add("Distributions")` to install the Distributions package.

Stacktrace:
 [1] require(into::Module, mod::Symbol)
   @ Base .\loading.jl:871
 [2] include
   @ .\Base.jl:386 [inlined]
 [3] include_package_for_output(pkg::Base.PkgId, input::String, depot_path::Vector{String}, dl_load_path::Vector{String}, load_path::Vector{String}, concrete_deps::Vector{Pair{Base.PkgId, UInt64}}, source::String)
   @ Base .\loading.jl:1213
 [4] top-level scope
   @ none:1
 [5] eval
   @ .\boot.jl:360 [inlined]
 [6] eval(x::Expr)
   @ Base.MainInclude .\client.jl:446
 [7] top-level scope
   @ none:1
in expression starting at C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\src\ValueOrientedRiskManagementInsurance.jl:1
ERROR: LoadError: Failed to precompile ValueOrientedRiskManagementInsurance [top-level] to C:\Users\elm\.julia\compiled\v1.6\jl_C50E.tmp.
Stacktrace:
 [1] error(s::String)
   @ Base .\error.jl:33
 [2] compilecache(pkg::Base.PkgId, path::String, internal_stderr::Base.TTY, internal_stdout::Base.TTY)
   @ Base .\loading.jl:1360
 [3] compilecache(pkg::Base.PkgId, path::String)
   @ Base .\loading.jl:1306
 [4] _require(pkg::Base.PkgId)
   @ Base .\loading.jl:1021
 [5] require(uuidkey::Base.PkgId)
   @ Base .\loading.jl:914
 [6] require(into::Module, mod::Symbol)
   @ Base .\loading.jl:901
in expression starting at C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs\make.jl:2

C:\proj\Rprojs\PS1908\julia\ValueOrientedRiskManagementInsurance\docs>

The package ValueOrientedRiskManagementInsurance compiles fine in my vscode session...

[mortenpi]

If you're compiling the docs from the command line, you definitely need to make sure that you've activated the docs/ environment (i.e. adding --project=docs/ to the julia call).

Our docs are oriented towards this CLI approach though, and what would probably be really helpful for users is to have a section describing a e.g. VSCode-based workflow. The only thing one really needs to do there though is run pkg> activate docs/ in the REPL before running anything in make.jl.

[roland-KA]

I've just been running into the same problem @reumle described. I'm new to Documenter, but surely not to Julia. So I agree that the beginners documentation needs some improvement 😀.

I haven't deved the package I want to document into the docs/-environment. Thinking about it, it becomes clear, that this is needed. But as a beginner to Documenter, it's not the first thing you think about.

[odow]

Closing in favor of #1413