Documenter.jl: /stable is always linking to the previous version

[tpoisot]

I'm building the documentation using github actions, and after TagBot creates a new tag + release, the stable version of the documentation is still the previous one - for example:

https://github.com/EcoJulia/GBIF.jl/runs/550632506?check_suite_focus=true#step:5:32

Is there something I am missing? I have no added options besides push_preview=true to the make.jl
file.

[mortenpi]

If you look at the gh-pages branch you see that the docs for 0.2.0 were never deployed. As far as I can tell, this is because the CI never ran for the tag/release, likely because you're missing the on.push.tags: '*' part in the CI config (e.g. see this). With the recommended list of triggers, it seems to work for e.g. Literate.jl.

[tpoisot]

It doesn't seem to be working - I have a new version that JuliaRegistrator picked up, TagBot created a new release, but despite the workflow file being seemingly correct (https://github.com/EcoJulia/SimpleSDMLayers.jl/tree/master/.github/workflows), there is no build happening after the tag.

Even separating the documentation part to its own file, and forcing a build by pushing to master, had no effect.

[tpoisot]

Here is the relevant part of the output:

~~~
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Info: Deployment criteria for deploying devbranch build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="EcoJulia/SimpleSDMLayers.jl" occurs in repo="github.com/EcoJulia/SimpleSDMLayers.jl.git"
│ - ✔ ENV["GITHUB_EVENT_NAME"]="push" is "push"
│ - ✔ ENV["GITHUB_REF"] matches devbranch="master"
│ - ✔ ENV["GITHUB_ACTOR"] exists
│ - ✔ ENV["GITHUB_TOKEN"] exists exists
└ Deploying: ✔
┌ Warning: Currently the GitHub Pages build is not triggered when using GITHUB_TOKEN for authentication. See issue #1177 (https://github.com/JuliaDocs/Documenter.jl/issues/1177) for more information.
└ @ Documenter ~/.julia/packages/Documenter/QQWIJ/src/deployconfig.jl:307

• [new branch] compathelper/new_version/2020-03-31-20-04-08-434-3808769898 -> upstream/compathelper/new_version/2020-03-31-20-04-08-434-3808769898
• [new branch] compathelper/new_version/2020-03-31-20-04-16-371-683931174 -> upstream/compathelper/new_version/2020-03-31-20-04-16-371-683931174
• [new branch] gh-pages -> upstream/gh-pages
• [new branch] master -> upstream/master
• [new tag] v0.0.1 -> v0.0.1
• [new tag] v0.1.0 -> v0.1.0
• [new tag] v0.2.0 -> v0.2.0

┌ Warning: removing stable and linking stable to v0.0.1.
└ @ Documenter ~/.julia/packages/Documenter/QQWIJ/src/Documenter.jl:621
[gh-pages 27a583f] build based on 6ffc933
~~~

The new v0.2.0 tag is detected correctly, but it's not picked up by documenter.

[mortenpi]

The * [new tag] v0.2.0 -> v0.2.0 part comes from Git when it clones the repository, not from Documenter. As far as I can tell, what is still missing is a CI job for the tag.. although I have no idea why -- I do see that you updated the CI workflow.

[lindnemi]

I am encountering the same problem with our repository.

[mortenpi]

Ok, it seems that the underlying issue is that the default TagBot setup that uses the GITHUB_TOKEN does not have the permissions to trigger documentation builds. But you can actually use Documenter's SSH key instead:

with:
  token: ${{ secrets.GITHUB_TOKEN }}
  ssh: ${{ secrets.DOCUMENTER_KEY }}

So the full TagBot.yml should look as follows:

name: TagBot
on:
  schedule:
    - cron: 0 * * * *
jobs:
  TagBot:
    runs-on: ubuntu-latest
    steps:
      - uses: JuliaRegistries/TagBot@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ssh: ${{ secrets.DOCUMENTER_KEY }}

(Thanks to @briochemc and @mileslucas for helping to figure this out!)

[briochemc]

(BTW no need to thank me, I did not figure anything out, I just copied it from another repo/issue yesterday, and I don't even remember where 😅)

[lindnemi]

I changed the Tagbot.yml, but the docs for the new version of our package are still not build. Do I have to release a new tag for the changes to take effect?

[mileslucas]

What I’ve done in the past that worked was to manually build the docs with prettyurls and manually organize the gh-pages branch. Then I pushed up to origin and the changes were immediate.

Eventually when I fixed my CI the next time TagBot triggered the Ci correctly all of my docs were properly updated and sym links set.

If there’s a less anecdotal method I’d love to hear it.

[mortenpi]

What I’ve done in the past that worked was to manually build the docs with prettyurls and manually organize the gh-pages branch. Then I pushed up to origin and the changes were immediate.

That, unfortunately, is the only way to do this at the moment. Unless you can find a way to trigger the CI for the tag manually. The symlinks (stable/ etc) and the version selector will sort themselves out once a master build deploys though, since they get recreated every time.

I do have the idea that we should allow tags with build identifiers to deploy as well, just for this purpose. I.e. that you could manually push another tag like v1.2.3+1 and have that deploy into v1.2.3/ as well.