Framework for adding refpages to docs.vulkan.org #2553
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Jul 28, 2025
oddhack
changed the title
oddhack
force-pushed
the
antora_refpages
branch
from
ccdbf81 to
e493925
Compare
oddhack
changed the title
Runs the same refpage extraction step, but sourced from the rewritten spec sources in the Antora spec component, and output to a new refpages component. Still need to: * Generate refpages nav.adoc from refpage list (ideally with some structure) * Set attributes in refpages antora.yml to refer to the spec component for partials and images * Rewrite xrefs relative to the spec component, instead of as links into the registry HTML spec (changes to genRef.py needed)
…ile-links attribute when building it
link to other refpages, not to the specification.
xref rewrites, since they need to be passed several levels deep. Move importFileModule to reflib.py for reuse by several scripts. Consistently pass around the full path to pageMap.py and xrefMap.py, not just the directory they're located in.
Use more consistent option / variable naming and capitalization when referring to maps. Pass spec module name correctly when building Antora refpage sources.
This is incomplete - aliases are not included because they are part of the same page as the API they alias. Also, extension refpages are not included yet.
Remove old apispec.adoc generated file and corresponding Makefile targets 'manhtml' and 'manpdf', and use a different proxy target when generating the refpage .adoc markup.
oddhack
force-pushed
the
antora_refpages
branch
from
34cd92f to
ee23fc3
Compare
Improve refpage nav.adoc generation. Still needs to handle pages in refpage_other_types and perhaps aliases need to be handled differently, but much closer.
it from the 'pageMap' of asciidoc anchors to specification filenames. Use more consistent f'' style for strings with imbedded variables.
generation, which was never published. Now includes nav links for aliases which link to the aliased page. Minor fixes to refpage block markup. Split diagnostics from warnings in refpage generation log. Still problematic: * Generated interface files (e.g. refpage.<extensionname>.adoc) for promoted extensions are not resolving e.g. slink: markup for APIs which are aliased to promoted APIs. * nav index is very long (3100 lines!) and while it does collapse at the level of first letters, it does not collapse at the level of refpage types (e.g. 'Structures', 'API Core Versions', etc.) Otherwise this is looking much better.
reducing complaints from Antora about unresolved xrefs, and otherwise improve markup consistency.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is sufficiently complete that we can start publishing refpages in the docs site (once related PRs for the docs site and UI repositories are merged), though we should not migrate to them until the bits below are finished. The refpages are incorporated as a separate component (like spec, proposals, guide, etc.) and internally link between themselves where possible, while links to non-API content link to the spec component. I believe all of this works. The remaining bits TBD are:
The approach is to run the same refpage extraction step as used for the published refpages today, but sourced from the rewritten spec sources in the Antora spec component, and output to a new refpages component.
Merging this doesn't affect the current site build, but once it is merged, to make the new module appear on the site we will need to also merge KhronosGroup/Vulkan-Site#121 and KhronosGroup/antora-ui-khronos#25 to actually include the module content in the generated site.
(once final bits completed, will close) #1723
Closes internal issue 2837