I’m trying to use the documenter package with a github action (for a crude package I’m trying to construct GitHub - dankelley/OceanAnalysis.jl: Julia code for oceanographic analysis), and am seeing problems with building 3 packages.
At first I thought it related to Documenter, and posted a question in an issue there (How to handle a GH action that raises LoadError on a package? · Issue #2770 · JuliaDocs/Documenter.jl · GitHub) but then I realized that the problem occurs on my own machine, too.
The problem (as I understand it, somewhat naively) seems to be that I get different behaviours for CLI julia instructions versus instructions I type in a console. (The instantiate I did within ] and in the base interactive level produced no output .)
I think the material I’ve pasted below illustrates the issue, although of course I’d be more than happy to provide other information. Maybe I should remove absolutely everything on my machine that relates to Julia and restart from scratch?
➜ git/OceanAnalysis.jl git:(main) julia --project=. -e "using Pkg; Pkg.instantiate()" &> dan; grep LoadE dan
ERROR: LoadError: ArgumentError: Package MbedTLS_jll [c8ffd9c3-330d-5841-b78e-0817d7145fa1] is required but does not seem to be installed:
ERROR: LoadError: Failed to precompile LibGit2_jll [e37daf67-58a4-590a-8e99-b0245dd2ffc5] to "/Users/kelley/.julia/compiled/v1.11/LibGit2_jll/jl_E9kxcW".
ERROR: LoadError: Failed to precompile LibGit2 [76f85450-5226-5b5a-8eaa-529ad045b433] to "/Users/kelley/.julia/compiled/v1.11/LibGit2/jl_5Vlr2G".
ERROR: LoadError: ArgumentError: Package MbedTLS_jll [c8ffd9c3-330d-5841-b78e-0817d7145fa1] is required but does not seem to be installed:
ERROR: LoadError: Failed to precompile LibGit2_jll [e37daf67-58a4-590a-8e99-b0245dd2ffc5] to "/Users/kelley/.julia/compiled/v1.11/LibGit2_jll/jl_GlrTIF".
ERROR: LoadError: Failed to precompile LibGit2 [76f85450-5226-5b5a-8eaa-529ad045b433] to "/Users/kelley/.julia/compiled/v1.11/LibGit2/jl_16vOAv".
➜ git/OceanAnalysis.jl git:(main) ✗ julia
_
_ _ _(_)_ | Documentation: https://docs.julialang.org
(_) | (_) (_) |
_ _ _| |_ __ _ | Type "?" for help, "]?" for Pkg help.
| | | | | | |/ _` | |
| | |_| | | | (_| | | Version 1.11.7 (2025-09-08)
_/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release
|__/ |
(@v1.11) pkg> instantiate
(@v1.11) pkg> ^C
julia> using Pkg; Pkg.instantiate()
This is my CI.yml: FLORIDyn.jl/.github/workflows/CI.yml at main · ufechner7/FLORIDyn.jl · GitHub
What I noticed, you do not use:
- uses: julia-actions/julia-buildpkg@v1
Did you try:
- uses: julia-actions/julia-buildpkg@v1
- name: Build documentation
run: |
julia --project=docs/ -e '
using Pkg
Pkg.develop(PackageSpec(path=pwd()))
Pkg.instantiate()'
julia --project=docs/ docs/make.jl
?
For building the documentation locally I use: FLORIDyn.jl/scripts/build_docu.jl at main · ufechner7/FLORIDyn.jl · GitHub
Thanks. I tried that, but still no luck. The same errors persist in the “Action” report.
But it’s not just the remote github action that causes problems. I see the problem also locally.
If I type
julia --project=. -e "using Pkg; Pkg.instantiate()"
at the unix CLI, I get over 300 lines of output, notably with LoadError messages (for MbedTLS_jll, LibGit2_jll and LibGit2).
However, by contrast, if I start a Julia console session (again, from the commandline – I don’t use vscode etc) and type
using Pkg; Pkg.instantiate()
there is no output, other than another julia> prompt, so it seems there is no problem with that. Also, if in that julia session I type
] instantiate
there is no output, other than a return to a pkg> prompt.
I think this is my core problem.
I’m sorry to be so dense. I’m still at the stage of not really knowing what activate, instantiate, update and several other things actually mean, or why I need to do steps like this both in my package and also within the docs subdirectory of that package. In other words, although I’m really enjoying Julia so far, I’m still a newbie.
What I did:
- I cloned you repository
- I run:
julia --project
using Pkg
Pkg.update()
That worked fine. Then I tried to build the documentation with:
include("scripts/build_docu.jl")
This failed because two PNG files were missing, maps.png and asmr.png.
I was able to create these png files using your scripts.
Now, I can successfully build the documentation using the include command above.
It also works without REPL:
ufechner@ufryzen:~/repos/OceanAnalysis.jl$ julia --project -e 'include("scripts/build_docu.jl")'
Activating project at `~/.julia/environments/v1.11`
Activating project at `~/repos/OceanAnalysis.jl`
Activating project at `~/.julia/environments/v1.11`
Activating project at `~/repos/OceanAnalysis.jl`
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="0.1.0"` for inventory from ../Project.toml
┌ Warning: Documenter could not auto-detect the building environment. Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/eoWm2/src/deployconfig.jl:93
✓ LiveServer listening on http://localhost:8000/ ...
(use CTRL+C to shut down)
^C
⋮ shutting down LiveServer… ✓
Can you reproduce my results?
Many thanks!!! I fiddled around a bit and got things working. I ended up removing ~/.julia and also the local Manifest.toml and Project.toml files and then adding things one by one. Then I added a few things to my .github/workflows/documentation.yml file so that it could pass the steps.
So now it works!
I really appreciate your advice.
Dan
I also noticed that you have no “Project.toml” in the doc folder. Normally, you should. Normally, Documenter.jl should not be a direct dependency of your project, because it is only needed for building the documentation, and normal users of your package will not do that.
Instead, Documenter should either be a test dependency, or you add it to the project in the doc folder. My Project.toml in that folder looks like this: FLORIDyn.jl/docs/Project.toml at main · ufechner7/FLORIDyn.jl · GitHub
Of course, yours probably should look a bit different, but you get the idea.