Antora ci

[gpx1000]

Description

This adds building the antora documentation to the CI for Vulkan Samples. This way we can capture any problems with the future changes to tutorials that are automatically harvested in creating the vulkan documentation site.

Fixes #1040
KhronosGroup/Vulkan-Site#82

NB: to see example of the build here:
https://gpx1000.github.io/Vulkan-Samples/samples/latest/README.html
When this is merged, the build job should publish to here:
Note that to make this work, need to change the settings for the repo to publish form the gh-pages branch.
https://khronosgroup.github.io/Vulkan-Samples/samples/latest/README.html

[oddhack]

@gpx1000 @martyj @TomAtkinsonArm trying to diagnose the publishing problem. First, there is an existing CI job jekyll-gh-pages.yml which already tries to publish there but fails. I do not know if this is intended to work, ever did work, or needs to work. It was created by @TomAtkinsonArm over a year ago according to git - Tom, can you comment? Without digging down into the details of the jekyll-gh-pages job, what it attempts to do is publish a subset of the repository files AFAICT.

Second, re authorizing the new Antora CI in this PR, the first thing I notice in the repo settings is that Pages "Build and deployment" is set to source "Github Actions". By contrast the Vulkan-Site settings uses source "Deploy from a branch". It's possible that changing this setting could address the permissions problem, and it would get us onto the same path as Vulkan-Site which does work. Changing it would probably break the jekyll job above even more than it's already broken, but since it's not working anyway, I propose to make that change as a first step.

[SaschaWillems]

Imo we should do exactly that. The github page deployment was an early attempt at publishing some form of documentation. We never really made that public and it probably doesn't work at all with asciidoc.

[gpx1000]

100% agree, we should retire the current GitHub job in favor of this.

[oddhack]

100% agree, we should retire the current GitHub job in favor of this.

@gpx1000 I was skimming over the recent minutes and noticed you commented "Waiting on Jon - I don’t have permissions to deprecate the path…unless someone has reason to keep github pages…". But I don't see a specific ask above? How about if:

• This pr gets rid of the jekyll-gh-pages.yml which I think we all agree, does not work.
• Someone (@SaschaWillems ?) who has Admin privs adds @gpx1000 to the team for this repo, and gives Admin as well, so you can do whatever setting-tweaking may be needed to get the gh-pages deployment working. I noted an inconsistency above with how Vulkan-Site is setup, but I'd rather leave it with you able to experiment with it without my needing to be in the loop.
• If both of those are done, is there anything else you would be waiting for me on?

[oddhack]

@SaschaWillems @gpx1000 it would be great to progress this. It's difficult for me even to pull the entire Samples repo, much less successfully set it up for Antora. The former might be network issues but I'm pretty certain the latter is because there are so many external submodules that can easily themselves have build problems. I'm not sure how the submodules are setup, but these problems are so difficult to diagnose from my PoV that I think we should be locking the Antora builds to specific known-good repository commits and submodule commits going forward. Having CI setup to validate the Antora build at a specific point in time should be helpful in that regard.

[SaschaWillems]

I'd love to help, but no idea what to do or if I can do anything at all (in regards to this issue). We talked about this on the last call. @gpx1000: What needs to be done to fix this?

[gpx1000]

Yep, this is on my todo list. I just need to edit the project settings in the github repo.

[SaschaWillems]

Can we get this merged/fixed? CI on main has been failing for months because the CI deploy step fails. That's kinda sad as this build error is easily visible on the main repo site.

If we can't merge this PR, a stop-gap would be to disable github deployment.

Any opinions on this?

[oddhack]

Can we get this merged/fixed? CI on main has been failing for months because the CI deploy step fails. That's kinda sad as this build error is easily visible on the main repo site.

If we can't merge this PR, a stop-gap would be to disable github deployment.

Any opinions on this?

I took a quick look at the build logs and noticed that while the build step is generating the same errors (more or less) that I see building the docs site as a whole, which is good, it is not generating a fatal error. So it goes on to the deploy job and fails there for other reasons.

From my perspective, the point of doing this is not so much to generate a viewable site as to detect the internal errors that filter through to the docs site (mostly dead xrefs for one reason or another), and prevent merging future PRs in this repo without fixing those issues.

So my thought is to do whatever is required to make the build job fail on antora errors, and to turn off the deploy step until a later time, if it's proving difficult to make function. I'm not sure what's up with the build error behavior, but there appears to be no option to turn ERROR reports from building the internal pages into actual fatal error status of the antora invocation. If so then capturing the stacktrace output and grepping it for ERROR strings might be the only option. We could ask on the Zulipchat group.

[gpx1000]

I guess what we can do is simply drop the deploy to github pages. For the life of me I can't figure out what github wants in order to accept this for this project. It works fine on my repo, but something with the way it's setup here refuses to keep my changes once I make them and do a test (i.e. it looks right then I rerun the test). I've been reading about it, but not really sure how to fix it. Maybe dropping pages for now and circling back when I'm less dumb is a good idea ;-)