From 82d1004487409b03c8b96b7cccabeafbbbec66df Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Mon, 29 Apr 2024 04:03:13 -0700 Subject: [PATCH] Refactor proposals into a separate Antora component See https://github.com/KhronosGroup/Vulkan-Site/issues/54 --- antora/.gitignore | 5 ++ antora/Makefile | 36 ++++++------- antora/README | 2 + antora/modules/ROOT/pages/index.adoc | 44 ---------------- antora/proposals/antora.yml | 22 ++++++++ .../modules/proposals/nav.adoc | 0 .../modules/proposals/pages/index.adoc | 0 antora/{ => spec}/antora.yml | 5 +- antora/{ => spec}/modules/ROOT/nav.adoc | 0 antora/spec/modules/ROOT/pages/index.adoc | 52 +++++++++++++++++++ config/attribs.adoc | 4 +- 11 files changed, 104 insertions(+), 66 deletions(-) create mode 100644 antora/.gitignore create mode 100644 antora/README delete mode 100644 antora/modules/ROOT/pages/index.adoc create mode 100644 antora/proposals/antora.yml rename antora/{ => proposals}/modules/proposals/nav.adoc (100%) rename antora/{ => proposals}/modules/proposals/pages/index.adoc (100%) rename antora/{ => spec}/antora.yml (86%) rename antora/{ => spec}/modules/ROOT/nav.adoc (100%) create mode 100644 antora/spec/modules/ROOT/pages/index.adoc diff --git a/antora/.gitignore b/antora/.gitignore new file mode 100644 index 000000000..25a21b0e3 --- /dev/null +++ b/antora/.gitignore @@ -0,0 +1,5 @@ +**/images +**/chapters +**/appendices +**/partials +**/pages/proposals diff --git a/antora/Makefile b/antora/Makefile index d922d1534..1973950dc 100644 --- a/antora/Makefile +++ b/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) diff --git a/antora/README b/antora/README new file mode 100644 index 000000000..0f6dbf53a --- /dev/null +++ b/antora/README @@ -0,0 +1,2 @@ +This is the staging area for the docs.vulkan.org +'spec' and 'proposals' modules. diff --git a/antora/modules/ROOT/pages/index.adoc b/antora/modules/ROOT/pages/index.adoc deleted file mode 100644 index 201a1866b..000000000 --- a/antora/modules/ROOT/pages/index.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// 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, 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 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 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 the various documentation modules and specs. - -The top contains a text searchbar. -It will suggest matches to search terms found in all the modules of the -site. - -== 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. diff --git a/antora/proposals/antora.yml b/antora/proposals/antora.yml new file mode 100644 index 000000000..daae55bdd --- /dev/null +++ b/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 diff --git a/antora/modules/proposals/nav.adoc b/antora/proposals/modules/proposals/nav.adoc similarity index 100% rename from antora/modules/proposals/nav.adoc rename to antora/proposals/modules/proposals/nav.adoc diff --git a/antora/modules/proposals/pages/index.adoc b/antora/proposals/modules/proposals/pages/index.adoc similarity index 100% rename from antora/modules/proposals/pages/index.adoc rename to antora/proposals/modules/proposals/pages/index.adoc diff --git a/antora/antora.yml b/antora/spec/antora.yml similarity index 86% rename from antora/antora.yml rename to antora/spec/antora.yml index 5def9916b..e0ca13ca8 100644 --- a/antora/antora.yml +++ b/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 diff --git a/antora/modules/ROOT/nav.adoc b/antora/spec/modules/ROOT/nav.adoc similarity index 100% rename from antora/modules/ROOT/nav.adoc rename to antora/spec/modules/ROOT/nav.adoc diff --git a/antora/spec/modules/ROOT/pages/index.adoc b/antora/spec/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..fad775e89 --- /dev/null +++ b/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. diff --git a/config/attribs.adoc b/config/attribs.adoc index bfd529026..64df0e6ad 100644 --- a/config/attribs.adoc +++ b/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