Refactor 'proposals' into a separate Antora component 'features'

README.adoc

@@ -27,6 +27,7 @@ LICENSE.adoc          Summary of licenses used by files in the repository
 ChangeLog.adoc        Change log summary for each public Vulkan spec update
 ChangeLogSC.adoc      Change log summary for each public Vulkan SC spec update
 Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
+antora/               Staging area for the docs.vulkan.org Antora 'proposals' and 'spec' modules
 appendices/           Specification appendices
 chapters/             Specification chapters
 proposals/            Design documents for extensions

antora/.gitignore

@@ -0,0 +1,8 @@
+# Copyright 2024 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+**/images
+**/chapters
+**/appendices
+**/partials
+**/pages/proposals

antora/Makefile

@@ -1,21 +1,21 @@
 # Copyright 2014-2024 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
-# Configure Vulkan spec Antora tree with generated files and transformed
+# Configure Vulkan-Docs Antora tree with generated files and transformed
 # markup files.
 # Branch selection will come later. For now it is the current branch.
 
 RMRF = rm -rf
 
 JSAPIMAP = ./gen/apimap.cjs
 XREFMAPS = $(PYXREFMAP) $(JSXREFMAP)
-PYXREFMAP = antora/xrefMap.py
-JSXREFMAP = antora/xrefMap.cjs
-JSPAGEMAP = antora/modules/ROOT/partials/gen/pageMap.cjs
+PYXREFMAP = antora/spec/xrefMap.py
+JSXREFMAP = antora/spec/xrefMap.cjs
+JSPAGEMAP = antora/spec/modules/ROOT/partials/gen/pageMap.cjs
 
-setup: setup_spec setup_proposals
+setup: setup_spec setup_features
 
-# Rewrite Vulkan spec sources and images into the module directory, ROOT
+# Rewrite Vulkan spec sources and images into the spec/module/ROOT
 # component
 # Page headers are added to pull in required attributes
 # Also creates apimap.cjs, pageMap.cjs, and xrefMap.cjs for use by the
@@ -37,8 +37,8 @@ xrefmaps:
 spec_pages:
 	scripts/antora-prep.py \
 	    -root . \
-	    -component $(shell realpath antora/modules/ROOT) \
-	    -xrefpath antora \
+	    -component $(shell realpath antora/spec/modules/ROOT) \
+	    -xrefpath antora/spec \
 	    -pageHeaders antora/pageHeaders-spec.adoc \
 	    -pagemappath $(JSPAGEMAP) \
 	    ./config/attribs.adoc \
@@ -48,39 +48,42 @@ spec_pages:
 	    `find ./gen ./chapters ./appendices -name '[A-Za-z]*.adoc' | grep -v /vulkanscdeviations.adoc` \
 	    $(JSAPIMAP)
 
-# Rewrite proposals into the module directory, 'proposals' component
+# Rewrite feature descriptions into the features/module/features component.
 # No additional pageHeaders required.
-setup_proposals: proposal_nav
+setup_features: features_nav
 	scripts/antora-prep.py \
 	    -root . \
-	    -component $(shell realpath antora/modules/proposals) \
-	    -xrefpath antora \
+	    -component $(shell realpath antora/features/modules/features) \
+	    -xrefpath antora/features \
 	    ./images/tile_image.svg \
 	    `find ./proposals -name '[A-Za-z]*.adoc'`
 
-# Construct the proposals nav.adoc from the current list of
-# proposals, so it remains up to date.
+# Construct the features nav.adoc from the current list of
+# features, so it remains up to date.
 # This could be merged into antora-prep.py but is very specific
-# to the proposals so that is pointless.
-proposal_nav:
-	scripts/antora-nav-proposals.py \
+# to the features module, so that is pointless.
+# We no longer include the proposal template.
+# To restore it, add
+#   -templatepath proposals/template.adoc
+# and uncomment that option in the script.
+features_nav:
+	scripts/antora-nav-features.py \
 	    -root . \
-	    -component $(shell realpath antora/modules/proposals) \
+	    -component $(shell realpath antora/features/modules/features) \
 	    -roadmappath proposals/Roadmap.adoc \
-	    -templatepath proposals/template.adoc \
 	    `find ./proposals -name 'VK_*.adoc'`
 
 # Files generated by 'setup' target
 ANTORA_GENERATED = \
-	antora/modules/ROOT/images \
-	antora/modules/ROOT/pages/appendices \
-	antora/modules/ROOT/pages/chapters \
-	antora/modules/ROOT/pages/gen \
-	antora/modules/ROOT/partials \
-	antora/modules/proposals/pages/proposals \
-	antora/modules/proposals/partials \
-	antora/modules/proposals/images \
-	antora/modules/proposals/nav.adoc \
+	antora/spec/modules/ROOT/images \
+	antora/spec/modules/ROOT/pages/appendices \
+	antora/spec/modules/ROOT/pages/chapters \
+	antora/spec/modules/ROOT/pages/gen \
+	antora/spec/modules/ROOT/partials \
+	antora/features/modules/features/pages/proposals \
+	antora/features/modules/features/partials \
+	antora/features/modules/features/images \
+	antora/features/modules/features/nav.adoc \
 	$(JSXREFMAP) \
 	$(PYXREFMAP)
 

antora/features/antora.yml

@@ -0,0 +1,23 @@
+# Copyright 2022-2024 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+name: features
+title: Vulkan Feature Descriptions
+version: latest
+start_page: features:index.adoc
+# stem (latexmath) support is provided by the @djencks/asciidoctor-mathjax
+# extension, loaded in the playbook.
+asciidoc:
+  attributes:
+    stem: latexmath
+    config: partial$config
+    chapters: partial$chapters
+    appendices: partial$appendices
+    generated: partial$gen
+    images: image$
+# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001
+#    imageopts: inline
+    imageopts: ''
+    refprefix: ''
+nav:
+- modules/features/nav.adoc

antora/modules/proposals/nav.adoc → antora/features/modules/features/nav.adoc

@@ -1,12 +1,14 @@
 // Copyright 2024 The Khronos Group Inc.
 // SPDX-License-Identifier: CC-BY-4.0
 
+// This file is generated by the scripts/antora-nav-features.py script.
+// To make changes, modify that script.
+
 :chapters:
 
-* xref:index.adoc[Vulkan Proposals]
-* Vulkan Roadmap
-** xref:proposals/Roadmap.adoc[]
-* Extension Proposals
+* xref:index.adoc[Vulkan Roadmap and Feature Descriptions]
+* xref:proposals/Roadmap.adoc[Vulkan Roadmap]
+* Feature Descriptions
 ** xref:proposals/VK_AMDX_shader_enqueue.adoc[]
 ** xref:proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc[]
 ** xref:proposals/VK_ANDROID_external_format_resolve.adoc[]
@@ -79,5 +81,3 @@
 ** xref:proposals/VK_NV_ray_tracing_validation.adoc[]
 ** xref:proposals/VK_QCOM_image_processing.adoc[]
 ** xref:proposals/VK_QCOM_tile_properties.adoc[]
-* Extension Proposal Template
-** xref:proposals/template.adoc[]

antora/features/modules/features/pages/index.adoc

@@ -0,0 +1,17 @@
+// Copyright 2022-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Vulkan Feature Descriptions
+
+This component includes all published extension feature descriptions, as
+well as the original rationale for the xref:proposals/Roadmap.adoc[Vulkan
+Roadmap] process which resulted in the
+xref:spec::appendices/roadmap.adoc[Roadmap 2022 and Roadmap 2024] milestones.
+
+When a Vulkan extension begins development, a "`proposal`" document is
+written outlining the proposed API.
+The proposal is the basis from which specification language is written.
+
+When the extension is published, the proposal - now referred to as a
+"`feature description`" - is retained to act as supplementary documentation
+on that extension.

antora/antora.yml → antora/spec/antora.yml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 name: spec
-title: Vulkan Specification and Proposals
+title: Vulkan Specification
 version: latest
 # stem (latexmath) support is provided by the @djencks/asciidoctor-mathjax
 # extension, loaded in the playbook.
@@ -14,10 +14,9 @@ asciidoc:
     appendices: partial$appendices
     generated: partial$gen
     images: image$
-# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/536
+# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001
 #    imageopts: inline
     imageopts: ''
     refprefix: ''
 nav:
 - modules/ROOT/nav.adoc
-- modules/proposals/nav.adoc

antora/spec/modules/ROOT/pages/index.adoc

@@ -0,0 +1,52 @@
+// Copyright 2022-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Vulkan Documentation
+
+include::{config}/attribs.adoc[]
+include::{generated}/specattribs.adoc[]
+
+
+== About
+
+link:https://docs.vulkan.org/[This site] gathers together several key Vulkan
+documents including specifications, extension proposals, guides, tutorials
+and samples into a single site.
+This allows searching and cross-linking across documents, to help navigate
+quickly to the information you need for developing Vulkan-based
+applications.
+
+For more information about and resources for using the Vulkan graphics API,
+see the Vulkan developer website at https://vulkan.org .
+
+This build of the site includes the Vulkan {SPECREVISION} API specification
+{APITITLE}, generated on {SPECDATE} {SPECREMARK}.
+
+
+== Navigation
+
+The site is organized in "`components`" (Antora terminology for
+specifications and other documents), each containing many "`pages`" (Antora
+terminology for a chapter of a specification, or other distinct piece of
+content for other components).
+
+The left navigation sidebar links to pages in the current component.
+
+The right navigation sidebar links to sections in the current page.
+
+The bottom-left button switches between components.
+
+The top navigation bar contains a text searchbox.
+If the "`In this component`" box is checked, search will be restricted to
+the current component.
+Otherwise, all components of the site are searched.
+
+
+== Site Information
+
+link:https://docs.vulkan.org/[This site] is generated using the
+link:https://docs.antora.org/[Antora] static site generator.
+
+If you need to report a problem or build the site yourself, start with the
+link:https://github.com/KhronosGroup/Vulkan-Site/[Vulkan-Site] repository on
+GitHub.

config/attribs.adoc

@@ -110,9 +110,11 @@ endif::VKSC_VERSION_1_0[]
 :glemulation: OpenGL / ES support
 
 
-// Link/xref prefix for the location of proposal documents.
+// Link/xref prefix for the location of feature description documents.
+// The Antora resource ID must change if the component or module layout of
+// the feature descriptions changes.
 :specRepositoryURL: https://github.com/KhronosGroup/Vulkan-Docs/tree/main/
-ifdef::site-gen-antora[:proposalRefPath: xref:proposals:]
+ifdef::site-gen-antora[:proposalRefPath: xref:features:features:]
 ifndef::site-gen-antora[:proposalRefPath: link:{specRepositoryURL}]
 
 // URL prefix for the GLSL extensions registry