Wrong Package Used in Documenter

General Usage
1

I was trying in vain to get a documention for TiledViews.jl up and running.
The issue is that the CI seems to install the last release version, rather than using the local Development Version, which is why the Documenter fails spectacularly:

However, locally, if I cd to the docs folder and run make.jl, everthing runs fine, if the Version that Installed there was intalled via dev ... in the package manager promt.

Any ideas, what is wrong in my setup, and how I can make the Documenter look for the local Development version (branch: main) instead of always using the previous release?

2

HI,

I looked at your make.jl and it seems it does not put your package into development mode itself – and while you locally might have done that, the CI does not do that itself automatically.

I would recommend two things

  1. The make.jl could first activate the environment you already seem to have in the docs/ folder anyways (I assume from the project.toml)
  2. while it is at that activation and such it could also just take the parent folder and set that in dev-mode
  3. it could even afterwards go back to the main env, but that is optional

An example is for example the docs I wrote at Manopt.jl/docs/make.jl at master · JuliaManifolds/Manopt.jl · GitHub – though those are maybe a bit verbose, the main ideas I mentioned above are the lines

(85 activate current folders env, 86 set parent in dev, 87-88 make sure all is resolved)

Hope that helps :slight_smile:

1 Like
3

Thanks a lot for the suggestion. I added this code with an additional @info line to the beginning of my make.jl.
But it did not change anything:

The @info command was not shown. I found out that even older attempts did already install Version 0.3.0, which is the newest version.
When I run this locally, it seems all fine:

julia> include("make.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.3.0"` for inventory from ..\Project.toml
┌ Warning: Documenter could not auto-detect the building environment. Skipping deployment.
└ @ Documenter C:\Users\pi96doc\.julia\packages\Documenter\ZlqFj\src\deployconfig.jl:76

So it is probably some other version incompatibiltiy?
These are my installed version in the main package:

  [613c443e] IndexFunArrays v0.2.7
  [98581153] NDTools v0.8.0
  [9a3f8284] Random v1.11.0
  [8dfed614] Test v1.11.0

and these are the ones in the docs directory:

  [e30172f5] Documenter v1.10.2
  [35a29f4d] DocumenterTools v0.1.20
  [ab21d65a] TiledViews v0.3.0 `..`

I see a difference in the NDTools.jl version number. Maybe this is causing the trouble…

4

Ah, I See. To add a bit of detail: The if checks whether the environment is already active and only activates it if necessary.
In you case it seems to be active on CI already.
Maybe move the other commands (your lines 6-9) out of the if then?

Otherwise I am not 100% sure where your errors come from, my main incentive was to move you to the right env and the right version first – that might even now work.

Where your errors then come from, I can not see that easily since that is somewhere in your package?
Is your package compatible with the versions loaded on CI? Do you load the same ones? So for example NDTools? If you are not compatible with versions the CI leads the errors might come from that?

5

Thanks again. Appreciated. It turned out, that the CI was basically fine and no need to add anything. The issue was that in the ci.yml (line 49) , the Julia Version for doc generation was set to 1.7 which then forced an old NDTools.jl which was incompatible with the current version.
No everything seems OK.

1 Like
6

Ah I did indeed not check the config for CI – well-spotted :slight_smile:

Great that you could find it!

1 Like
7

Just a note: a better practice nowadays is to use [sources] in docs/Project.toml to have Pkg.jl automatically resolve things correctly for you (works if you build docs on 1.11 and above). This way you can remove all the Pkg.develop hacks.

It should just be something like in most cases:

[deps]
...
TiledView = "<fill in the UUID>"

[sources]
TiledViews = { path = ".." }

E.g. this is how Documenter does it itself nowdays too.

4 Likes
8

Neat! I will try that when I work on my documentation next.

9

Thank. Nice tip! I ended up removing the Pkg hacks anyway and it worked well also without any of this? Am I missing a point, or is it really necessary to add this [sources] tag?

10

The julia-actions/julia-docdeploy action does it for you:

But without [sources], you’d still have to call Pkg.develop manually when you’re e.g. building the docs locally.

1 Like
11

I see. I did build locally but I guess it worked only because I used ]dev .. in the docs directory :slight_smile:
The [sources] tag seems to be a much better way.

12

I also switched to [sources] now, very nice solution :slight_smile: