diff --git a/README.adoc b/README.adoc index 46850ee1c..0cedfce33 100644 --- a/README.adoc +++ b/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 diff --git a/antora/.gitignore b/antora/.gitignore new file mode 100644 index 000000000..0f17d1816 --- /dev/null +++ b/antora/.gitignore @@ -0,0 +1,8 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +**/images +**/chapters +**/appendices +**/partials +**/pages/proposals diff --git a/antora/Makefile b/antora/Makefile index d922d1534..999676072 100644 --- a/antora/Makefile +++ b/antora/Makefile @@ -1,7 +1,7 @@ # 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. @@ -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 +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) diff --git a/antora/features/antora.yml b/antora/features/antora.yml new file mode 100644 index 000000000..88fb77da6 --- /dev/null +++ b/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 diff --git a/antora/modules/proposals/nav.adoc b/antora/features/modules/features/nav.adoc similarity index 94% rename from antora/modules/proposals/nav.adoc rename to antora/features/modules/features/nav.adoc index 92509776a..de0fb702a 100644 --- a/antora/modules/proposals/nav.adoc +++ b/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[] diff --git a/antora/features/modules/features/pages/index.adoc b/antora/features/modules/features/pages/index.adoc new file mode 100644 index 000000000..86ba71c09 --- /dev/null +++ b/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. 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/modules/proposals/pages/index.adoc b/antora/modules/proposals/pages/index.adoc deleted file mode 100644 index cd48bb7a0..000000000 --- a/antora/modules/proposals/pages/index.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Copyright 2022-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -= Vulkan Proposals Start Page - -The Proposals module includes the Vulkan Roadmap, the Vulkan 2022 Profile -Roadmap, and all published extension proposals. - diff --git a/antora/setup_vulkan b/antora/setup_vulkan deleted file mode 100755 index 2a15a4531..000000000 --- a/antora/setup_vulkan +++ /dev/null @@ -1,57 +0,0 @@ -#!/bin/bash -# Copyright 2014-2024 The Khronos Group Inc. -# SPDX-License-Identifier: Apache-2.0 - -# setup_vulkan - configure Vulkan spec antora tree with generated files - -vkspec=/home/tree/git/vulkan - -cd $vkspec - -# Branch selection may come later. For now, use the current branch -# git checkout antora - -set -x - -if true ; then - # Generate intermediate files (for rewriting) and HTML target (for - #scanning anchors) - makeSpec QUIET=@ -clean -spec all \ - -genpath gen \ - generated jsapi html - - # Generate the map (anchor name -> [ chapter anchor, anchor title ] - # (xrefMap.py / xrefMap.cjs) from spec HTML - scripts/map_html_anchors.py gen/out/html/vkspec.html -pyfile antora/xrefMap.py -jsfile antora/xrefMap.cjs -fi - -# Rewrite spec sources and images into module directory - -# Module directory -dir=modules - -# ROOT component - Vulkan spec -# Page headers are added to pull in required attributes -# Also creates pageMap.cjs for use by the Antora version of the spec macros -component=$vkspec/antora/${dir}/ROOT -scripts/antora-prep.py \ - -root . \ - -component $component \ - -xrefpath antora \ - -pageHeaders antora/pageHeaders-spec.adoc \ - -pagemappath antora/modules/ROOT/partials/gen/pageMap.cjs \ - ./config/attribs.adoc \ - ./config/copyright-ccby.adoc \ - ./config/copyright-spec.adoc \ - ./images/*.svg \ - `find ./gen ./chapters ./appendices -name '[A-Za-z]*.adoc'` \ - ./gen/apimap.cjs - -# proposals component - Vulkan extension proposals -# No pageHeaders required. -component=$vkspec/antora/${dir}/proposals -scripts/antora-prep.py \ - -root . \ - -component $component \ - -xrefpath antora \ - `find ./proposals -name '[A-Za-z]*.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..2aea0b3be --- /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..e022493d5 100644 --- a/config/attribs.adoc +++ b/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 diff --git a/scripts/antora-nav-proposals.py b/scripts/antora-nav-features.py similarity index 66% rename from scripts/antora-nav-proposals.py rename to scripts/antora-nav-features.py index 2923314da..25ad0ebea 100755 --- a/scripts/antora-nav-proposals.py +++ b/scripts/antora-nav-features.py @@ -3,11 +3,11 @@ # Copyright 2022-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 -"""Used to generate the Antora `nav.adoc` for the Vulkan spec proposals module. +"""Used to generate Antora `nav.adoc` for the Vulkan 'features' module. -Usage: `antora-nav-proposals.py [-root path] -component path [-roadmap path] [-template path] files` +Usage: `antora-nav-features.py [-root path] -component path [-roadmap path] files` -- `-root` is the root path (repository root, usually) relative to which spec +- `-root` is the root path (repository root, usually) relative to which files are processed. Defaults to current directory if not specified. - `-component` is the path to the module and component in which converted files are written (e.g. the component directory under which pages/, @@ -15,10 +15,11 @@ - `-navfile` is the filename (not path) of the navigation file, and defaults to `nav.adoc` if not present - `-roadmappath` is the path to the Vulkan Roadmap, which is grouped - separately from the individual extension proposals. + separately from the individual feature descriptions. - `-templatepath` is the path to the proposal template, which is grouped - separately from the individual extension proposals. -- Remaining arguments are paths to individual proposals. + separately from the individual extension feature descriptions. + This argument is no longer used. +- Remaining arguments are paths to individual feature descriptions. The only file generated is `component`/nav.adoc, which is the top-level navigation file for the module. @@ -39,18 +40,18 @@ help='Specify root directory under which files are located (default current directory)') parser.add_argument('-component', action='store', dest='component', required=True, - help='Specify module / component directory in which the proposal navigation file "nav.adoc" is written') + help='Specify module / component directory in which the features navigation file "nav.adoc" is written') parser.add_argument('-navfile', action='store', dest='navfile', default='nav.adoc', required=False, - help='Specify filename of proposal module navigation file (default nav.adoc)') + help='Specify filename of features module navigation file (default nav.adoc)') parser.add_argument('-roadmappath', action='store', dest='roadmappath', default=None, required=False, help='Specify path to Roadmap.adoc containing the Vulkan 2022 Roadmap') parser.add_argument('-templatepath', action='store', dest='templatepath', default=None, required=False, - help='Specify path to the template.adoc used to create new proposals') + help='Specify path to the template.adoc used to create new feature descriptions') parser.add_argument('files', metavar='filename', nargs='*', - help='Specify name of a single extension proposal to index') + help='Specify name of a single feature description to index') args = parser.parse_args() @@ -67,31 +68,38 @@ # Boilerplate - print('// Copyright 2024 The Khronos Group Inc.', file=fp) - print('// {}-License-Identifier: CC-BY-4.0\n'.format('SPDX'), file=fp) - print(':chapters:\n', file=fp) - print('* xref:index.adoc[Vulkan Proposals]', file=fp) + print('// Copyright 2024 The Khronos Group Inc.', + '// {}-License-Identifier: CC-BY-4.0'.format('SPDX'), + '', + '// This file is generated by the scripts/antora-nav-features.py script.', + '// To make changes, modify that script.', + '', + ':chapters:', + '', + '* xref:index.adoc[Vulkan Roadmap and Feature Descriptions]', + sep='\n', file=fp) # Roadmap if args.roadmappath is not None: - print('* Vulkan Roadmap', file=fp) relpath = os.path.relpath(os.path.abspath(args.roadmappath), args.root) - print(f'** xref:{relpath}[]', file=fp) + print(f'* xref:{relpath}[Vulkan Roadmap]', + sep='\n', file=fp) - # Individual extension proposals - print('* Extension Proposals', file=fp) - proposals = set() + # Individual feature descriptions + print('* Feature Descriptions', file=fp) + features = set() for filename in args.files: relpath = os.path.relpath(os.path.abspath(filename), args.root) - proposals.add(relpath) - for relpath in sorted(proposals): + features.add(relpath) + for relpath in sorted(features): print(f'** xref:{relpath}[]', file=fp) # Template if args.templatepath is not None: - print('* Extension Proposal Template', file=fp) relpath = os.path.relpath(os.path.abspath(args.templatepath), args.root) - print(f'** xref:{relpath}[]', file=fp) + print('* Extension Feature Descriptions', + f'** xref:{relpath}[]', + sep='\n', file=fp) fp.close()