Vulkan Documentation Project Site Generator

This repository is used to build an experimental integrated Vulkan documentation site using the Antora site generator.

An online version of the resulting site is located at https://docs.vulkan.org/spec/latest/index.html.

The site generator currently combines these components:

Vulkan Specification and Proposals
Vulkan Guide
Vulkan Samples
Vulkan Tutorial
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.

Files

docs-site/ - Antora project directory.
- 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

Installation

You will need the current long-term support version of Node.js (20.x).

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/cli@3.1 @antora/site-generator@3.1 @djencks/asciidoctor-mathjax @antora/lunr-extension

Running Antora

The simplest way 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 steps in .github/workflows/ci.yml adapted to your local OS environment. In particular, other repositories containing the Antora UI and content for the various components must be pulled and configured before the site can be built. Currently, we do not take advantage of Antora’s capability of pulling 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 and more transparent. At present, you should clone the repositories as follows:

mkdir -p /home/tree/git
cd /home/tree/git
git clone git@github.com:KhronosGroup/Vulkan-Site.git
cd Vulkan-Site
for repo in antora-ui-khronos Vulkan-Docs Vulkan-Guide Vulkan-Samples Vulkan-Tutorial ; do
    git clone git@github.com:KhronosGroup/$repo
done

Once the repositories are cloned, 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.

At this point, you should be able to build the UI via:

cd antora-ui-khronos
npm install
npx update-browserslist-db@latest
./node_modules/gulp/bin/gulp.js --version
./node_modules/gulp/bin/gulp.js bundle
cp build/ui-bundle.zip ../docs-site

Next, prepare the sources via

for dir in docs-site Vulkan-Docs ; do
    (cd $dir && npm install)
done
(cd Vulkan-Tutorial/antora && make setup_tutorial)
(cd docs-site && make prepare_components)
(cd Vulkan-Samples && cmake -H"." -B"build/unix" -DVKB_GENERATE_ANTORA_SITE=ON)

Finally, run Antora to build the site

(cd docs-site && npx antora antora-playbook.yml --stacktrace)

The result can be viewed by pointing a browser at the root of the site tree:

# Or whatever browser you prefer instead of Chromium
$ chromium docs-site/build/site/index.html

Feedback

Please provide feedback on the documentation project using the Vulkan-Site issues tracker.