This repository is used to build the integrated Vulkan Documentation Site Antora site generator.
The site generator currently combines these components:
-
Vulkan Specification, Reference Pages, and Feature Proposals
-
More components will be added in the future.
This repository contains only the Antora “playbook” describing the various documentation components and how to integrate them, and related files needed to build the site using the playbook.
Content for individual components comes from the repositories hosting those components, and issues with individual components should be reported in those repositories.
-
docs-site/- Antora project directory.-
docs-site/Makefile- Makefile for pulling and configuring component repositories. -
docs-site/antora-playbook.yml- Antora playbook. -
docs-site/node_modules- Antora executable and related modules. -
docs-site/package.json/package-lock.json- Node.js infrastructure / module database.
-
You will need the current long-term support version of Node.js (24 as of the last update to this README).
Antora itself is preinstalled under docs-site/node_modules/ along with all
Javascript dependencies.
If and only if you need to install these modules elsewhere, the installation
can be reproduced by:
node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E @antora/[email protected] @antora/[email protected] @djencks/asciidoctor-mathjax @antora/lunr-extensionThe simplest way to build is to rely on the GitHub Actions CI.
CI will pull all the other needed repositories and build an artifact
fullSite.zip which is downloadable from the CI run under the Actions
GitHub menu.
If you need to build locally, you can use the following steps:
|
Note
|
Currently, we do not use Antora’s ability to pull content directly from Github. Instead, the repositories must be available locally on specific paths hard-wired into the playbook, followed by steps to prepare their content for use with Antora. Eventually, we expect to use the Antora Collector extension to make this process simpler. |
# Or other path as desired
mkdir -p /home/tree/git
cd /home/tree/git
git clone [email protected]:KhronosGroup/Vulkan-Site.git
cd Vulkan-Site
make initThis pulls this repository, then uses the Makefile target to
pull the component and Antora UI repositories and configure
their submodules and node modules, if any.
At this point you will need to be running in an environment containing all the tools to build the Vulkan Specification, as described in the Vulkan-Docs BUILD document. We recommend using the Khronos-provided Docker image described in that document, rather than trying to install everything yourself and keep it up to date.
Most of the component repositories require preparing the sources for Antora before doing a site build:
make prep-sourcesPlease provide feedback on the documentation project using the Vulkan-Site issues tracker.
