Add CI step for Antora documentation build

[SaschaWillems]

We should add a CI step that builds the Antora documentation for this repo to make sure we don't introduce changes that break the build for the Vulkan documentation site.

See KhronosGroup/Vulkan-Site#82

[spencer-lunarg]

@oddhack do you know what would be a good way to "test" the Vulkan-Guide build?

is going asciidoctor guide.adoc good enough?

(I have been doing more and more github action stuff, so happy to take this on)

[gpx1000]

Actually, I have a solution I've been working on in the tutorial I can port here or you're welcome to do so.
https://github.com/KhronosGroup/Vulkan-Tutorial/blob/main/.github/workflows/build-antora-doc.yml

To get a full picture of how I set it up including the other build steps, here's the PR where I set it up:
KhronosGroup/Vulkan-Tutorial#76
(i.e. just add a small playbook in the root and you can build antora for just the guide).

[spencer-lunarg]

If you have a solution for Vulkan-Tutorials, please bring it over here, will be happy to review and get it in

[oddhack]

Unfortunately a "successful" Antora build doesn't actually validate as much as would be good. In particular, it emits warning messages about unresolved links, but the CI step would succeed. As a result, some components can have dozens or hundreds of unresolved links which won't be noticed unless someone pays close attention to the very long build logs.

There might be a way to boost the severity of the warnings into errors which if we can, would probably be a good idea. N.b. I don't think we should do this for the overall site build because it would become impossible to publish updates some weeks, but it might be a good idea for the individual component CI.

I think Steve's approach is very reasonable. It will not catch cross-component link errors but we do very little of that, anyway. So far.

[gpx1000]

Yeah, my plan is to use regex and sed. Fail the build if it sees something like warning or error. I'll make it a little more intelligent than that but general approach for when I'm home

…

On Mon, Jul 7, 2025, 7:13 PM Jon Leech ***@***.***> wrote: *oddhack* left a comment (KhronosGroup/Vulkan-Guide#261) <#261 (comment)> Unfortunately a "successful" Antora build doesn't actually validate as much as would be good. In particular, it emits warning messages about unresolved links, but the CI step would succeed. As a result, some components can have dozens or hundreds of unresolved links which won't be noticed unless someone pays close attention to the very long build logs. There might be a way to boost the severity of the warnings into errors which if we can, would probably be a good idea. — Reply to this email directly, view it on GitHub <#261 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5IAYYGGZQAJNXIWMVEHQL3HMSMLAVCNFSM6AAAAACA7ONWGGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANBXGEZDCMZVGA> . You are receiving this because you were assigned.Message ID: ***@***.***>

[gpx1000]

The PR attached to this issue captures warnings and errors and fails the build if they are found. grep didn't want to do it, but more than one way to use regex. Anyway, this should work for the components and keep it out of the wider site build. I want to keep the site build a more of a final assembly type of thing. I agree, cross-component link errors should be only thing we really need to watch out for in the full site build. I might be talked into regex for those types of errors and failing builds then, but it might be something we want to maintain a method of overriding. Anyway, this approach should be ready for review.