// Copyright 2022-2024 The Khronos Group Inc. // SPDX-License-Identifier: CC-BY-4.0
= Vulkan Documentation Project Site Generator
This repository is used to build an experimental integrated Vulkan documentation site using the link:https://antora.org/[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:
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:
== 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:
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 link:https://github.com/KhronosGroup/Vulkan-Docs/blob/main/BUILD.adoc[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:
Next, prepare the sources via
Finally, run Antora to build the site
The result can be viewed by pointing a browser at the root of the site tree:
== Feedback
Please provide feedback on the documentation project using the link:https://github.com/KhronosGroup/Vulkan-Site/issues[Vulkan-Site issues tracker].