Refactor proposals into a separate Antora component

See KhronosGroup/Vulkan-Site#54

antora/.gitignore

@@ -0,0 +1,5 @@
+**/images
+**/chapters
+**/appendices
+**/partials
+**/pages/proposals

antora/Makefile

@@ -9,13 +9,13 @@ 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
 
-# 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,12 +48,12 @@ 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 proposals into the proposals/module/proposals component.
 # No additional pageHeaders required.
 setup_proposals: proposal_nav
 	scripts/antora-prep.py \
 	    -root . \
-	    -component $(shell realpath antora/modules/proposals) \
+	    -component $(shell realpath antora/proposals/modules/proposals) \
 	    -xrefpath antora \
 	    ./images/tile_image.svg \
 	    `find ./proposals -name '[A-Za-z]*.adoc'`
@@ -65,22 +65,22 @@ setup_proposals: proposal_nav
 proposal_nav:
 	scripts/antora-nav-proposals.py \
 	    -root . \
-	    -component $(shell realpath antora/modules/proposals) \
+	    -component $(shell realpath antora/proposals/modules/proposals) \
 	    -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/proposals/modules/proposals/pages/proposals \
+	antora/proposals/modules/proposals/partials \
+	antora/proposals/modules/proposals/images \
+	antora/proposals/modules/proposals/nav.adoc \
 	$(JSXREFMAP) \
 	$(PYXREFMAP)
 

antora/README

@@ -0,0 +1,2 @@
+This is the staging area for the docs.vulkan.org
+'spec' and 'proposals' modules.

antora/proposals/antora.yml

@@ -0,0 +1,22 @@
+# Copyright 2022-2024 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+name: proposals
+title: Vulkan Proposals
+version: latest
+# 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/proposals/nav.adoc

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

@@ -111,8 +111,10 @@ endif::VKSC_VERSION_1_0[]
 
 
 // Link/xref prefix for the location of proposal documents.
+// The Antora resource ID must change if the component or module layout of
+// the proposals changes.
 :specRepositoryURL: https://github.com/KhronosGroup/Vulkan-Docs/tree/main/
-ifdef::site-gen-antora[:proposalRefPath: xref:proposals:]
+ifdef::site-gen-antora[:proposalRefPath: xref:proposals:proposals:]
 ifndef::site-gen-antora[:proposalRefPath: link:{specRepositoryURL}]
 
 // URL prefix for the GLSL extensions registry