Draft: Initial cut at the docs site Antora build

Makefile

@@ -22,14 +22,18 @@ KATEX	 = katex
 ROOTDIR  = $(CURDIR)
 # Where the spec files are
 SPECDIR  = $(CURDIR)
+# Path to scripts used in generation
+SCRIPTS  = $(ROOTDIR)/scripts
 # Path to configs and asciidoc extensions used in generation
 CONFIGS  = $(ROOTDIR)/config
 # Images used by the spec. These are included in generated HTML now.
 IMAGEPATH = $(SPECDIR)/images
 
 # Target directories for output files
 # OUTDIR - base directory in which outputs are generated
-OUTDIR	 = $(ROOTDIR)/out
+OUTDIR	  = $(ROOTDIR)/out
+PYXREFMAP = $(GENERATED)/xrefMap.py
+PYPAGEMAP = $(GENERATED)/pageMap.py
 
 # PDF Equations are written to SVGs, this dictates the location to store
 # those files (temporary)
@@ -72,6 +76,8 @@ ATTRIBOPTS   = -a revdate="$(SPECDATE)" \
 	       -a chapters=$(SPECDIR)/chapters \
 	       -a images=$(IMAGEPATH) \
 
+# Where intermediate files go. OUTDIR is not ideal.
+GENERATED    = $(OUTDIR)
 # Top-level spec source file
 SPECSRC      = $(SPECDIR)/core.adoc
 # Static files making up sections of the API spec.
@@ -142,7 +148,66 @@ $(OUTDIR):
 #	  $(QUIET) echo "Warning: please verify the spec outputs build without changes!"
 #	  $(PYTHON) $(REFLOW) $(REFLOWOPTS) $(SPECSRC) $(SPECFILES)
 
+# Cross-references of anchors to spec chapters they lie within.
+# Used by setup_spec_antora target.
+
+xrefmaps: $(PYXREFMAP)
+
+$(PYXREFMAP): $(OUTDIR)/glsl.html
+	$(QUIET)$(PYTHON) $(SCRIPTS)/map_html_anchors.py \
+	    $(OUTDIR)/glsl.html -pyfile $(PYXREFMAP)
+
+# Generate all Antora module content
+setup_antora: setup_spec_antora
+
+# Generate Antora spec module content by rewriting spec sources
+# Individual files must be specified last
+
+ANTORA_SPECMODULE = antora/glsl/modules/glsl
+
+# The list of files can be long enough to exceed system limits on
+# arguments lists, so instead of passing them on the command line they
+# are stored in a separate file.
+ANTORA_FILELIST = $(GENERATED)/antoraFileList.txt
+
+# Additional individual files to include
+ANTORA_EXTRAFILES = \
+	./config/attribs.adoc \
+	./config/headerattribs.adoc \
+	./config/copyright-spec.adoc \
+	./images/*.svg
+
+# chapters/interfacematching.adoc is specific to ESSL, which we are not
+# currently generating.
+setup_spec_antora pagemap $(PYPAGEMAP): xrefmaps
+	$(QUIET)find ./chapters -name '[A-Za-z]*.adoc' | \
+	    grep -v interfacematching.adoc > $(ANTORA_FILELIST)
+	$(QUIET)ls -1 $(ANTORA_EXTRAFILES) >> $(ANTORA_FILELIST)
+	$(QUIET)$(PYTHON) $(SCRIPTS)/antora-prep.py \
+	    -root . \
+	    -component $(shell realpath $(ANTORA_SPECMODULE)) \
+	    -xrefpath $(GENERATED) \
+	    -pageHeaders antora/pageHeaders-spec.adoc \
+	    -pypagemap $(PYPAGEMAP) \
+	    -filelist $(ANTORA_FILELIST)
+
 # Clean generated and output files
 
-clean:
+clean: clean_antora
 	$(QUIET)$(RMRF) $(OUTDIR)
+
+# Files generated by 'setup_antora' target
+# Omit antora/features/modules/features/nav.adoc which is generated, but
+# also checked in.
+CLEAN_ANTORA_PATHS = \
+	$(ANTORA_FILELIST) \
+	antora/glsl/modules/glsl/images \
+	antora/glsl/modules/glsl/pages/appendices \
+	antora/glsl/modules/glsl/pages/chapters \
+	antora/glsl/modules/glsl/pages/partials \
+	antora/glsl/modules/glsl/partials
+
+clean_antora:
+	$(QUIET)$(RMRF) $(CLEAN_ANTORA_PATHS)
+
+

antora/.gitignore

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

antora/glsl/antora.yml

@@ -0,0 +1,20 @@
+# Copyright 2022-2024 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+name: glsl
+title: OpenGL Shading Language Specification
+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
+    images: image$
+# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001
+#    imageopts: inline
+    imageopts: ''
+    refprefix: ''
+nav:
+- modules/glsl/nav.adoc

antora/glsl/modules/glsl/nav.adoc

@@ -0,0 +1,30 @@
+// Copyright 2022-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Navigation page for GLSL spec in Antora
+
+// This corresponds to ../core.adoc - each top-level chapter is referenced
+// below in the same order
+
+:test: 0
+ifeval::["{test}"=="0"]
+* xref:chapters/preamble.adoc[]
+* xref:chapters/introduction.adoc[]
+* xref:chapters/overview.adoc[]
+* xref:chapters/basics.adoc[]
+* xref:chapters/variables.adoc[]
+* xref:chapters/operators.adoc[]
+* xref:chapters/statements.adoc[]
+* xref:chapters/builtins.adoc[]
+* xref:chapters/builtinfunctions.adoc[]
+* xref:chapters/interfacematching.adoc[]
+* xref:chapters/grammar.adoc[]
+* xref:chapters/iocounting.adoc[]
+* xref:chapters/acknowledgements.adoc[]
+* xref:chapters/references.adoc[]
+* xref:chapters/spirvmappings.adoc[]
+endif::[]
+
+ifeval::["{test}"=="1"]
+* xref:chapters/introduction.adoc[]
+endif::[]

antora/glsl/modules/glsl/pages/index.adoc

@@ -0,0 +1,41 @@
+// Copyright 2022-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= OpenGL Shading Language Documentation
+
+include::{config}/attribs.adoc[]
+
+== About
+
+This site includes the OpenGL Shading Language
+{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.

antora/pageHeaders-spec.adoc

@@ -0,0 +1,7 @@
+// Copyright 2022-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Boilerplate to include in spec pages.
+include::{config}/headerattribs.adoc[]
+
+include::{config}/attribs.adoc[]

chapters/grammar.adoc

@@ -584,12 +584,14 @@ _type_specifier_ : ::
     _type_specifier_nonarray_ +
     _type_specifier_nonarray_ _array_specifier_
 
+[[array_specifier]]
 _array_specifier_ : ::
     _LEFT_BRACKET_ _RIGHT_BRACKET_ +
     _LEFT_BRACKET_ _conditional_expression_ _RIGHT_BRACKET_ +
     _array_specifier_ _LEFT_BRACKET_ _RIGHT_BRACKET_ +
     _array_specifier_ _LEFT_BRACKET_ _conditional_expression_ _RIGHT_BRACKET_
 
+[[type_specifier_nonarray]]
 _type_specifier_nonarray_ : ::
     _VOID_ +
     _FLOAT_ +

chapters/variables.adoc

@@ -2788,7 +2788,7 @@ It is a compile-time error if it does not include one of the storage qualifiers
 It may optionally include <<layout-qualifiers,layout qualifiers>>, the
 <<storage-qualifiers,auxiliary storage qualifier>> *patch*, and the
 <<the-precise-qualifier,precise qualifier>>.
-*buffer* blocks may additionally include <<memory qualifiers>>.
+*buffer* blocks may additionally include <<memory-qualifiers>>.
 It is a compile-time error to include any other qualifiers.
 
 _member-list_ declares the variables that are to be grouped into the block.

config/headerattribs.adoc

@@ -0,0 +1,52 @@
+// Copyright 2008-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+:GLSL:
+
+// The remainder of this file is used in the Antora build, and corresponds
+// directly to attributes set in the specification title file, core.adoc.
+
+// {GLSL} or {ESSL} must be set in the invoking command line to generate
+// the corresponding specification
+//
+// {apiname} - API name, OpenGL or OpenGL ES
+// {apispec} - API specification name
+// {apiversion} - API version number (major.minor)
+// {slname} - shading language name
+// {version} - shading language __VERSION__ string (majorminor)
+// {minor} - shading language version number (major.minor)
+// {revision} - shading language revision number
+// {revnumber} - full major.minor.revision number
+// {authors} - shading language spec authors (for title page)
+
+ifdef::GLSL[]
+:apiname: OpenGL
+:apiversion: 4.6
+:slabbrev: GLSL
+:version: 460
+:minor: 4.60
+:authors: Graeme Leese, Broadcom (Editor) ; John Kessenich (Author) ; Dave Baldwin and Randi Rost (Version 1.1 Authors)
+:compiletimeerror: a compile-time error
+:highp:
+:mediump:
+:lowp:
+endif::GLSL[]
+
+ifdef::ESSL[]
+:apiname: OpenGL ES
+:apiversion: 3.2
+:slabbrev: GLSL ES
+:version: 320
+:minor: 3.20
+:authors: Graeme Leese, Broadcom (Editor) ; Robert J. Simpson, Qualcomm ; John Kessenich ; Dave Baldwin and Randi Rost (Version 1.1 Authors)
+:compiletimeerror: an error
+:highp: highp
+:mediump: mediump
+:lowp: lowp
+endif::ESSL[]
+
+:apispec: {apiname} Specification
+:slname: {apiname} Shading Language
+:revision: 9
+:revnumber: {minor}.{revision}
+:regtitle: pass:q,r[^®^]