GitHub Pages build error
quinnj opened this issue · 8 comments
For the last couple of releases, I've been receiving the following docs page build error as an email:
I originally thought this was just some configuration error in our own Julia-doc-building stack, but since those have been resolved, the 2.6.2 release seems to have successfully been generated/built: https://github.com/apache/arrow-julia/tree/gh-pages/v2.6.2, but navigating to the docs page: https://apache.github.io/arrow-julia/stable/, still redirects to a very old release (2.2.0), which confirms the email saying the pages build error is preventing the docs site from reflecting the accurate current version.
Doing a little googling on the email error message, I found a thread where this comment specifically mentioned that if the org is is on a legacy billing plan, then that can lead to this build error. @kou, can I ask for your help in trying to confirm if this is what the core issue is for us? Is the apache GitHub org on the legacy billing plan, thus preventing our GitHub Pages from having symlinks? It would at least be helpful to confirm if that's the issue, though I don't know what exactly would be the next steps from that point (is there a way to push the apache org to use the non-legacy billing system? perhaps we need to manually restructure how we do the doc generation/symlinks for the repo?).
Also a friendly ping to yoannchaudet in case they are in a position to help diagnose the issue for us here, since they seemed so helpful in other threads involving this kind of GH pages error.
oops, actual ping, cc: @yoannchaudet
We disabled symlinks support in our legacy build infrastructure for Pages back in February.
Two solutions:
- Remove symlinks on your
gh-pagesbranch (or "dereference" them, i.e. duplicate content) - Enable Actions in your organization, for that, you may need to upgrade your billing plan to a non-legacy one for GitHub Actions to become available
GitHub Pages is now leveraging Actions when it can for running builds and deployments because it provides a much nicer and secure sandbox.
As a hack, to make Documenter dereference them, you might be able to overload this function to create copies instead of symlinks: https://github.com/JuliaDocs/Documenter.jl/blob/c6bc92c79c1cb450875692417b40bea2e0c1d983/src/deploydocs.jl#L450-L456
Can we use https://apache.arrow.org/julia/ (ASF's Web infra) instead of https://apache.github.io/arrow-julia/ (GitHub Pages)? (I'm not sure whether symlinks work on ASF's Web infra or not...)
For example, DataFusion uses ASF's Web infra: https://arrow.apache.org/datafusion/
To use ASF's Web infra, we just need to push Web contents to asf-site branch with the following .asf.yaml configuration:
# publishes the content of the `asf-site` branch to
# https://arrow.apache.org/julia/
publish:
whoami: asf-site
subdir: juliaSee also DataFusion's .asf.yaml: https://github.com/apache/arrow-datafusion/blob/main/.asf.yaml
DataFusion automates Web contents deployment by GitHub Actions: https://github.com/apache/arrow-datafusion/blob/main/.github/workflows/docs.yaml
@kou, I went ahead and merged the PR. It didn't work initially because the .asf.yaml file isn't copied to the asf-site branch, but I manually pushed it to the branch and now it's working for /dev.
@mortenpi, do you know how it works when we do a new release? The .asf.yaml file should not be removed from the asf-site branch, right? Like, a new release will just add to the asf-site branch but not remove anything already there? I'm just wondering if we need to automate the copying of .asf.yaml to the branch each deploy or if doing it once manually should suffice.
Working doc page for reference: https://arrow.apache.org/julia/dev/
@mortenpi, do you know how it works when we do a new release? The
.asf.yamlfile should not be removed from theasf-sitebranch, right?
Nope, Documenter shouldn't touch it, and it should just now stay there.
As a side note: I would suggest manually copying over the old versions from gh-pages to asf-site, so that they would also be available on the new site.