-
Notifications
You must be signed in to change notification settings - Fork 466
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2227 from gpx1000/update-main-antora-page
update the main landing page for antora
- Loading branch information
Showing
1 changed file
with
7 additions
and
81 deletions.
There are no files selected for viewing
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,92 +1,18 @@ | ||
| // Copyright 2022-2023 The Khronos Group Inc. | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| = Vulkan Documentation Project Demo | ||
| = Vulkan Documentation | ||
|
|
||
| include::{config}/attribs.adoc[] | ||
| include::{generated}/specattribs.adoc[] | ||
|
|
||
| == Status (2023-05-05) | ||
|
|
||
| This site is a proof of concept showing how to get several of our Vulkan | ||
| specifications, proposals, and guides into a single integrated documentation | ||
| site. | ||
| Please provide feedback by raising | ||
| link:https://github.com/KhronosGroup/Vulkan-Site/issues[issues] in the | ||
| project repository. | ||
|
|
||
| Status: | ||
|
|
||
| * Substantially complete - all content for a full Vulkan 1.3 core {plus} | ||
| all extensions Specification is included here. | ||
| * Internal links between pages work, although the different modules are | ||
| not heavily crosslinked. | ||
| * Math rendering now works properly. | ||
| * UI and CSS are lightly modified from Antora defaults and will continue | ||
| to be customized. The UI is built from the | ||
| link:https://github.com/KhronosGroup/antora-ui-khronos[antora-ui-khronos] | ||
| repository. | ||
| * There are some known performance problems with the site search | ||
| interface. In particular, typing `VK_` in the searchbox will cause a | ||
| very long delay. These are being worked upstream. | ||
| * Currently, building the site requires local repository clones of the | ||
| components (Vulkan specification, proposals, and guide). Eventually we | ||
| will make use of Antora Collector, which will allow pulling branches to | ||
| build directly from github. | ||
|
|
||
| Incorporation of additional components such as the SPIR-V Specification will | ||
| require more authoring work, and discussion with the relevant working | ||
| groups. | ||
|
|
||
| == About | ||
| This site gathers together several key Vulkan documents including specifications, guides, tutorials and samples into a single site allowing for easy cross-searching and cross-linking across documents to help navigate quickly to the information you need for developing Vulkan-based applications. For more details on the Vulkan graphics API, see here: https://vulkan.org | ||
|
|
||
| == Navigation | ||
|
|
||
| The left sidebar links to pages in the current "`module`" - spec / | ||
| proposals, or guide. "`pages`" map onto chapters in the Vulkan | ||
| Specification. | ||
| As currently configured, the spec and proposals are two separate modules in | ||
| the same repository, so they both appear in the same sidebar (proposals are | ||
| way down at the bottom - keep scrolling). | ||
| The left sidebar links to pages in the current spec. Proposals are available at the bottom of the sidebar links for the spec. | ||
|
|
||
| The right sidebar is sections within the current page. | ||
|
|
||
| The bottom-left button switches between modules. Pages can also directly | ||
| crosslink between modules, such as these links to the | ||
| xref:spec:proposals:index.adoc[Vulkan Proposals] and | ||
| xref:guide::index.adoc[Vulkan Guide] module start pages. | ||
|
|
||
| The top contains a text searchbar using the Antora Lunr extension. | ||
| It will suggest matches to search terms found in all of the modules of the | ||
| site. | ||
|
|
||
|
|
||
| == Implementation | ||
|
|
||
| The goals of this demo are: | ||
|
|
||
| * Demonstrate several Vulkan document sets integrated in Antora | ||
| ** Done. | ||
| * Show that Antora can be used with our documents without significantly | ||
| impacting the existing spec markup, toolchain, and outputs. | ||
| ** Done. The demo is not built from a specification repository fork. It is | ||
| using current `main` branch with an Antora overlay which provide the | ||
| basic document structure and a set of scripts which do light | ||
| transformations on spec chapters and appendices to Antora conventions. | ||
| ** This means there need be no impact of Antora to ongoing spec | ||
| development activity, including generating Promoter ratification | ||
| candidates. | ||
|
|
||
|
|
||
| == Future Plans | ||
|
|
||
| In the near term: | ||
|
|
||
| * Improve navigation / add additional resources in top navbar | ||
| * Possibly alter the site theme to something closer to the current Vulkan | ||
| Specification | ||
| * Incorporate feedback from the developer community | ||
| The bottom-left button switches between the various documentation modules and specs. | ||
|
|
||
| In the longer term, our hope is that this approach to publishing Vulkan | ||
| documentation can eventually be used to replace the separate sites and | ||
| documents we use to publish today, and that we can add more modules with | ||
| other types of Vulkan and Vulkan-adjacent documentation. | ||
| The top contains a text searchbar. It will suggest matches to search terms | ||
| found in all the modules of the site. |