Documenter not uploading previews of pull requests

Tooling
,
1

I have Documenter working nicely and deploying my main-branch docs to gh-pages — including both dev, stable, and the various releases. But now I want to see what the docs look like in a PR. From what I can tell of this announcement and the documentation, Documenter should do this for me when I add the argument push_preview=true in the deploydocs function]. More specifically, it should add a folder under my gh-pages branch named preview, and a subfolder named PR15 (for PR #15 in my repo), which should then get served as usual when I go to the appropriate URL.

While the github action is running, it doesn’t seem to care about this new argument. The docs build properly, but near the end, all I see is this:

┌ Info: Deployment criteria for deploying devbranch build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="moble/SphericalFunctions.jl" occurs in repo="github.com/moble/SphericalFunctions.jl.git"
│ - ✔ ENV["GITHUB_EVENT_NAME"]="push" is "push"
│ - ✘ ENV["GITHUB_REF"] matches devbranch="main"
│ - ✔ ENV["GITHUB_ACTOR"] exists and is non-empty
│ - ✔ ENV["GITHUB_TOKEN"] exists and is non-empty
└ Deploying: ✘

Since I’m making the PR in a branch (from main), that third test fails, and it evidently doesn’t deploy for that reason. Is there something else I’m supposed to do? I’ve seen the warning about forks, but this is not a fork.

(In case it helps, the PR is here. There are lots of changes, but I suppose the only relevant one should be to docs/make.jl.)

2

I don’t know about the deployment stuff, but if it would be sufficient for you to preview on your computer, you can use LiveServer.jl to serve the content of docs/build to localhost. You’d better set clean = false in the call to makedocs.

3

If you look at the CI you see here

that it currently only deploys on main.
In your CI you could move to

- uses: julia-actions/julia-docdeploy@releases/v1

see for example Manopt.jl/documenter.yml at master · JuliaManifolds/Manopt.jl · GitHub (but that is just a little bit simpler in CI, maybe not the error),

I am not sure about your devbranch keyword, but it does not do harm, I think.
You are missing push_preview=true here

cf. for example

or see the description at Public · Documenter.jl

For example this CI run shows that you do not get the check for push_preview it seems? The following is what a recent CI run on my repo does

edit: Oh for your code I missed that I looked at master. Looking at your CI – you are still running Documenter 0.26 – maybe updating that to 0.27 helps? Though not sure.

4

Thanks for taking a look. Like you said in your edit, I can confirm that I am actually using push_preview=true.

Also, I should have pointed out that I tried both with and without the devbranch keyword. The only difference without it is that instead of

│ - ✘ ENV["GITHUB_REF"] matches devbranch="main"

it looks for the non-existent master branch, and I get

│ - ✘ ENV["GITHUB_REF"] matches devbranch="master"

Looking at your code, I realized that I was indeed using a somewhat older CI setup, so I ran PkgTemplate to see what the current recommended setup looks like, and modified my docs.yml to emulate it. In particular, I used this julia-docdeploy action that I hadn’t seen before.

Long story short: I get the same result. It still sees that GITHUB_REF is not “main”, and still skips deployment.

5

Ah, but it does appear to be true that Documenter 0.26 is pretty out of date, so I’ll look into what’s keeping that so low.

EDIT: Hmm. Maybe it’s that compat line in docs/Project.toml that specifically says 0.26…

6

Same result with Documenter v0.27.24. :frowning:

7

I should have checked the issues more carefully: the solution is explained here. The action was triggered on all pushes, and not on PRs. This commit changed that in my repo, and the preview was successfully created.

Thanks for the help!

2 Likes
8

Ah, that I did not check, great that you found it!