Add refpages module to site build

[oddhack]

Should not be merged until KhronosGroup/Vulkan-Docs#2553 is merged.

NOTE: edit branch selection for Vulkan-Docs in Actions ci.yml after merging, so it will pull from main branch again.

Closes #75
Closes #117

[oddhack]

@gpx1000 @marty-johnson59 @SaschaWillems this is sufficiently finished that I'd like to merge all the bits (site, Antora UI, and spec) and start publishing the refpages. Please comment if you're OK (or not) with that - there is nothing holding it up on the spec side as it does not affect the existing artifacts in the registry, and it's frustrating to deal with three separate, mutually dependent PRs being outstanding to progress this.

There is a prototype at https://docs.vulkan.org/sandbox/refpages/site/refpages/latest/refpages/index.html for the time being. Some minor cleanup still needs to be done to make some of the internal links resolve correctly, but as these are not immediately replacing the existing refpages, that's not a big deal.

This does increase site generation time and space consumed significantly, mostly because the navigation index for the refpages has 3100 entries in it and, therefore, makes each of the thousands of refpage HTML files about 10x as long as it would otherwise be. This is not a showstopper as the pages still load pretty fast - and only affects pages in the refpage component - but it is annoying. I have an ask in on the Antora chat and in worst case, we could do away with the full-up, extensive navbar and rely mostly on search.

[oddhack]

I have an ask in on the Antora chat and in worst case, we could do away with the full-up, extensive navbar and rely mostly on search.

Oh, encouragingly there is an Antora extension which handles this by shipping JSON encoding of the nav and building the nav panel on the client side. That could ideally just solve the problem: https://antora.zulipchat.com/#narrow/channel/282400-users/topic/Approaches.20to.20long.20navigation.20index.20.2B.20short.20pages.20.3D.3E.20bloated/with/534861189

[marty-johnson59]

OK by me. This looks really good!

[SaschaWillems]

LGTM. That's a great addition to the docs site, and having a nested navigation is a nice thing. 👍🏻

Noticed a few minor things while looking at the sandbox:

• The Constants entry in the navigation does not link to anything
• Link to VK_ENABLE_BETA_EXTENSIONS does not work

A more serious issues are page load times. It's always 3~4s before I can actually interact with the site. Maybe that's related to the sandbox, but every page load takes several seconds for me. Might be related to the search issue, if that's the case we should finally fix that.

[gpx1000]

I just profiled the page, it is the search. Downloading the index takes 1.26 seconds, expanding the index takes 1 second, and memory loading takes 4 seconds in this PR. It's not the fault of this PR, but it does expand the index which increases the problem. Gimme a few days to iterate on improving the search load. I think the solution is going to be a search index per module which would impact this PR.

[oddhack]

A more serious issues are page load times. It's always 3~4s before I can actually interact with the site. Maybe that's related to the sandbox, but every page load takes several seconds for me.

N.b. the sandbox is served from the same machine and filesystem as the main docs site, so it's relatively unlikely that would ever be a factor in relative performance.

We keep running into search issues, so I wonder if we should bite the bullet and move to a cloud search engine. There are some Antora integrations for such although I believe they're commercial products.

[gpx1000]

Looking at the profiling reported, there's plenty of room to fix the search in a more permanent way, (search index per module with threading). The reason we keep running into it is we keep adding to the search-index without fixing the search so the problem just gets larger. That's entirely on me. I'll get the search fixed.

[gpx1000]

https://gpx1000.github.io/Vulkan-Site/spec/latest/index.html <-- proof of concept for the search working faster. I suggest we take #121 (this PR) before we take the search PR #129.

I think this should fix the search issues mentioned above.

[oddhack]

Telecon: signed off along with antora-ui and Vulkan-Docs refpage PRs, once search improvements are merged. Will need to tweak this slightly to refer to main branch instead of test branches in the CI yml.

[gpx1000]

FYI, search improvements have been merged.