Refactor proposals into a separate Antora component (#2358)

* Refactor proposals into a separate Antora component

See KhronosGroup/Vulkan-Site#54

* Fix REUSE CI check

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

@@ -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/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