KhronosGroup / KhronosGroup/Vulkan-Samples

Broken / out of date links & Antora build

Open
#1,529 0 comments 0 reactions 1 assignee Claimed by @SaschaWillems View on GitHub
documentation
Dominant language
C++
Stars
5.4k
Forks
835
Avg merge
2h 16m
Merged PRs (30d)
1

Description

I ran 'linkchecker' over the docs site and turned up the following, which were the bulk of bad links in the site:

* Framework source file links

https://docs.vulkan.org/samples/latest/framework/README.html has a bunch of links to source files which are all dead. Either the link: targets could be qualified with an attribute to point to the github repository, or the ROOT/attachments directory could have these included when building the Antora staging area, and the link: targets be changed to xref: targets again qualified by an attribute which expands differently depending on github vs. Antora builds.

(Or the README could have the direct links removed).

* Refpages links from sample READMEs

A lot of README files under samples/ link to the old refpages in the Vulkan registry. They do get redirected to the docs site but it would be good to do a bulk edit using sed of

> https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkBlah.html

->

> https://docs.vulkan.org/refpages/latest/refpages/source/VkBlah.html

(maybe with an attribute containing the lengthy prefix), or better yet, to

> xref:refpages:refpages:source/VkBlah.adoc

in the Antora build (n.b. for the docs site proposals component, I do this by editing xrefs when creating the Antora staging area). There are 200+ of these spread across multiple READMEs and a few other files. Not a bug exactly, but they really dominate the linkchecker results and slow things down a tiny bit.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.