diff --git a/.github/scripts/check_chapter_references.py b/.github/scripts/check_chapter_references.py index f375a18..dc79dd7 100644 --- a/.github/scripts/check_chapter_references.py +++ b/.github/scripts/check_chapter_references.py @@ -16,7 +16,6 @@ # Paths to the files that need to be checked README_PATH = "README.adoc" -GUIDE_PATH = "guide.adoc" NAV_PATH = "antora/modules/ROOT/nav.adoc" # Directories to scan for chapter files @@ -96,31 +95,6 @@ def check_readme_references(chapter_files): print(f"Error checking README.adoc: {e}") return list(chapter_files.values()) -def check_guide_references(chapter_files): - """ - Check if all chapter files are referenced in guide.adoc. - Returns a list of files that are not referenced. - """ - try: - with open(GUIDE_PATH, 'r', encoding='utf-8') as f: - guide_content = f.read() - - missing_files = [] - for file_path, info in chapter_files.items(): - # Convert path to the format used in guide.adoc - rel_path = file_path.replace(CHAPTERS_DIR + "/", "") - - # Check if the file is referenced in guide.adoc - # The pattern needs to match both include:{chapters}file.adoc[] and include::{chapters}file.adoc[] - if not (re.search(rf'include:\{{chapters\}}{re.escape(rel_path)}', guide_content) or - re.search(rf'include::\{{chapters\}}{re.escape(rel_path)}', guide_content)): - missing_files.append(info) - - return missing_files - except Exception as e: - print(f"Error checking guide.adoc: {e}") - return list(chapter_files.values()) - def check_nav_references(chapter_files): """ Check if all chapter files are referenced in nav.adoc. @@ -193,54 +167,6 @@ def update_readme(missing_files): print(f"Error updating README.adoc: {e}") return False -def update_guide(missing_files): - """ - Update guide.adoc to include missing chapter references. - Returns True if the file was updated, False otherwise. - """ - if not missing_files: - return False - - try: - with open(GUIDE_PATH, 'r', encoding='utf-8') as f: - content = f.readlines() - - # Find appropriate sections to add the missing files - extensions_section_idx = None - main_section_idx = None - - for i, line in enumerate(content): - if "= When and Why to use Extensions" in line: - extensions_section_idx = i - elif "= Using Vulkan" in line: - main_section_idx = i - - if extensions_section_idx is None or main_section_idx is None: - print("Could not find appropriate sections in guide.adoc") - return False - - # Add missing files to appropriate sections - for file_info in missing_files: - rel_path = file_info["path"].replace(CHAPTERS_DIR + "/", "") - - if file_info["is_extension"]: - # Add to extensions section - content.insert(extensions_section_idx + 2, f"include::{{chapters}}{rel_path}[]\n\n") - extensions_section_idx += 2 # Adjust index for next insertion - else: - # Add to main section - content.insert(main_section_idx + 2, f"include::{{chapters}}{rel_path}[]\n\n") - main_section_idx += 2 # Adjust index for next insertion - - # Write updated content back to file - with open(GUIDE_PATH, 'w', encoding='utf-8') as f: - f.writelines(content) - - return True - except Exception as e: - print(f"Error updating guide.adoc: {e}") - return False - def update_nav(missing_files): """ Update nav.adoc to include missing chapter references. @@ -301,27 +227,22 @@ def main(): # Check if all chapter files are referenced in the three files readme_missing = check_readme_references(chapter_files) - guide_missing = check_guide_references(chapter_files) nav_missing = check_nav_references(chapter_files) print(f"Missing from README.adoc: {len(readme_missing)}") - print(f"Missing from guide.adoc: {len(guide_missing)}") print(f"Missing from nav.adoc: {len(nav_missing)}") # Update files if needed readme_updated = update_readme(readme_missing) - guide_updated = update_guide(guide_missing) nav_updated = update_nav(nav_missing) if readme_updated: print("Updated README.adoc") - if guide_updated: - print("Updated guide.adoc") if nav_updated: print("Updated nav.adoc") # Return non-zero exit code if any files were missing references - if readme_missing or guide_missing or nav_missing: + if readme_missing or nav_missing: print("Some chapter files were missing references and have been added.") return 1 else: diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index e41850f..ca73264 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -7,30 +7,20 @@ While open for contributions from all, there are a few contribution rules in pla The main design goal for the Vulkan Guide is to be "`lean`" and prevent any duplication of information. When possible the Vulkan Guide should guide a user to another resource via a hyperlink. -== Ways to Contribute +== Repo Structure -* Fixing a typo, grammar error, or other minor change -** Please feel free to make a PR and it will hopefully get merged in quickly. -* Adding new content -** If you think the guide needs another page, please raise an issue of what topic you feel is missing. This is not a requirement, but we hope to avoid people spending thier valuable time creating a PR for something that doesn't quite belong in the guides. -** If adding another link, clarification, or any other small blurb then a PR works. The addition of information needs to not be redundant and add meaningful value to the guide. -* Feel the guide is not accurately portraying a topic -** There are a lot of ways to use Vulkan and the guide is aimed to be as objective as possible. This doesn't mean that the current information on the Vulkan Guide might be slightly incorrect. Please raise an issue what you feel is incorrect and a solution to how you would improve it. +- `README.adoc` is the landing page if viewing from github +- `antora/modules/ROOT/pages/index.adoc` is the landing page if viewing from docs.vulkan.org -== Images +== Adding a new chapter -All images must be no wider than 1080px. This is to force any large images to be resized to a more reasonable size. +When adding a new chapter, make sure to add the `.adoc` to both `README.adoc` and `antora/modules/ROOT/nav.adoc` == Markup -The Guide has been converted from Markdown to Asciidoc markup format. It is -possible to view the individual chapters (pages) as before, starting with -the repository root README.adoc, or to generate a single document containing -each chapter using 'make guide.html' with the 'asciidoctor' command-line -tool installed. +The Guide was converted from Markdown to Asciidoc markup format in the past. -We have added experimental support for the Antora site generator under the -`antora/` directory. +We have added support for the Antora site generator under the `antora/` directory. See https://github.com/KhronosGroup/Vulkan-Site for details and links to a site incorporating the Vulkan specification, proposals, and this guide. diff --git a/Makefile b/Makefile deleted file mode 100644 index 7670beb..0000000 --- a/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# Copyright 2021 The Khronos Group, Inc. -# -# SPDX-License-Identifier: CC-BY-4.0 - -TARGETS = README.adoc guide.adoc $(wildcard chapters/[A-Za-z]*.adoc) $(wildcard chapters/extensions/[A-Za-z]*.adoc) - -all: guide.html - -guide.html: $(TARGETS) - asciidoctor --failure-level WARNING -b html5 guide.adoc - -GENERATED = guide.html -clean: - -rm -f $(GENERATED) diff --git a/README.adoc b/README.adoc index 137ff2e..45742be 100644 --- a/README.adoc +++ b/README.adoc @@ -29,7 +29,7 @@ The Vulkan Guide is designed to help developers get up and going with the world [NOTE] ==== -The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc` +The Vulkan Guide content is also viewable from https://docs.vulkan.org/guide/latest/index.html ==== :leveloffset: 1 diff --git a/antora/modules/ROOT/pages/index.adoc b/antora/modules/ROOT/pages/index.adoc index b44f002..4e8d21c 100644 --- a/antora/modules/ROOT/pages/index.adoc +++ b/antora/modules/ROOT/pages/index.adoc @@ -6,6 +6,8 @@ image::vulkan_logo.png[Vulkan Logo] image::khronos_logo.png[Khronos logo] endif::[] -// Extracted from boilerplate at start of guide.adoc +// This text appears as https://docs.vulkan.org/guide/latest/index.html The Vulkan Guide is designed to help developers get up and going with the world of Vulkan. It is aimed to be a light read that leads to many other useful links depending on what a developer is looking for. All information is intended to help better fill the gaps about the many nuances of Vulkan. + +This page is generated from https://github.com/KhronosGroup/Vulkan-Guide diff --git a/guide.adoc b/guide.adoc deleted file mode 100644 index aabf90e..0000000 --- a/guide.adoc +++ /dev/null @@ -1,320 +0,0 @@ -// Copyright 2019-2022 The Khronos Group, Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -= Vulkan^®^ Guide -:regtitle: pass:q,r[^®^] -The Khronos{regtitle} Vulkan Working Group -:data-uri: -:icons: font -:toc2: -:toclevels: 2 -:max-width: 100% -:numbered: -:source-highlighter: rouge -:rouge-style: github - -image::images/vulkan_logo.png[Vulkan Logo] -image::images/khronos_logo.png[Khronos logo] - -// Switch imagesdir for chapters/ includes so they can also load as single pages -:imagesdir: chapters -// Use {images} as base path for images -:images: images/ - -// Use {chapters} as base path for individual chapters, to allow single -// pages to work properly as well. Must have trailing slash. -// Implicit {relfileprefix} does not work due to file hierarchy -:chapters: chapters/ - -The Vulkan Guide is designed to help developers get up and going with the world of Vulkan. It is aimed to be a light read that leads to many other useful links depending on what a developer is looking for. All information is intended to help better fill the gaps about the many nuances of Vulkan. - -:leveloffset: 1 - -= Logistics Overview - -include::{chapters}what_is_vulkan.adoc[] - -include::{chapters}what_vulkan_can_do.adoc[] - -include::{chapters}vulkan_spec.adoc[] - -include::{chapters}platforms.adoc[] - -include::{chapters}checking_for_support.adoc[] - -include::{chapters}versions.adoc[] - -include::{chapters}vulkan_release_summary.adoc[] - -include::{chapters}what_is_spirv.adoc[] - -include::{chapters}portability_initiative.adoc[] - -include::{chapters}vulkan_cts.adoc[] - -include::{chapters}development_tools.adoc[] - -include::{chapters}validation_overview.adoc[] - -include::{chapters}decoder_ring.adoc[] - -= Using Vulkan - -include::{chapters}deprecated.adoc[] - -include::{chapters}ide.adoc[] - -include::{chapters}descriptor_arrays.adoc[] - -include::{chapters}loader.adoc[] -include::{chapters}swapchain_semaphore_reuse.adoc[] - -include::{chapters}buffer_device_address.adoc[] - -include::{chapters}layers.adoc[] -include::{chapters}push_constants.adoc[] - - -include::{chapters}checking_for_support.adoc[] - -include::{chapters}querying_extensions_features.adoc[] -include::{chapters}loader.adoc[] - -include::{chapters}vulkan_release_summary.adoc[] - -include::{chapters}enabling_extensions.adoc[] -include::{chapters}portability_initiative.adoc[] - -include::{chapters}validation_overview.adoc[] - -include::{chapters}enabling_features.adoc[] -include::{chapters}mapping_data_to_shaders.adoc[] - -include::{chapters}vulkan_spec.adoc[] - -include::{chapters}spirv_extensions.adoc[] -include::{chapters}depth.adoc[] - -include::{chapters}decoder_ring.adoc[] - -include::{chapters}formats.adoc[] -include::{chapters}formats.adoc[] - -include::{chapters}vulkan_cts.adoc[] - -include::{chapters}queues.adoc[] -include::{chapters}hlsl.adoc[] - -include::{chapters}atomics.adoc[] - -include::{chapters}wsi.adoc[] -include::{chapters}enabling_features.adoc[] - -include::{chapters}dynamic_state.adoc[] - -include::{chapters}windowing_audio_input.adoc[] - -include::{chapters}pnext_and_stype.adoc[] -include::{chapters}sparse_resources.adoc[] - -include::{chapters}vertex_input_data_processing.adoc[] - -include::{chapters}synchronization.adoc[] -include::{chapters}queues.adoc[] - -include::{chapters}enabling_extensions.adoc[] - -// Switch imagesdir for chapters/extensions/ includes so they can also load as single pages, -include::{chapters}image_copies.adoc[] - -// then switch it back again -include::{chapters}shader_memory_layout.adoc[] - -// :imagesdir: chapters/images/extensions -include::{chapters}threading.adoc[] - -// :images: images/ -include::{chapters}common_pitfalls.adoc[] - -include::{chapters}vulkan_profiles.adoc[] - -include::{chapters}extensions/VK_KHR_synchronization2.adoc[] -include::{chapters}protected.adoc[] - -include::{chapters}descriptor_dynamic_offset.adoc[] - -include::{chapters}synchronization_examples.adoc[] -include::{chapters}synchronization_examples.adoc[] - -include::{chapters}pipeline_cache.adoc[] - -include::{chapters}swapchain_semaphore_reuse.adoc[] -include::{chapters}querying_extensions_features.adoc[] - -:imagesdir: chapters -include::{chapters}ways_to_provide_spirv.adoc[] - -include::{chapters}primitive_topology.adoc[] - -include::{chapters}memory_allocation.adoc[] -include::{chapters}dynamic_state_map.adoc[] - -include::{chapters}memory_allocation.adoc[] - -include::{chapters}sparse_resources.adoc[] -include::{chapters}development_tools.adoc[] - -include::{chapters}wsi.adoc[] - -include::{chapters}protected.adoc[] -include::{chapters}robustness.adoc[] - -include::{chapters}spirv_extensions.adoc[] - -include::{chapters}buffer_device_address.adoc[] -include::{chapters}pnext_and_stype.adoc[] - -include::{chapters}platforms.adoc[] - -include::{chapters}pipeline_cache.adoc[] -include::{chapters}what_is_vulkan.adoc[] - -include::{chapters}extensions/VK_KHR_image_format_list.adoc[] - -include::{chapters}extensions/translation_layer_extensions.adoc[] - -include::{chapters}location_component_interface.adoc[] - -include::{chapters}extensions/VK_KHR_synchronization2.adoc[] - -include::{chapters}threading.adoc[] -include::{chapters}extensions/ray_tracing.adoc[] - -include::{chapters}what_is_spirv.adoc[] - -include::{chapters}extensions/VK_KHR_draw_indirect_count.adoc[] - -include::{chapters}extensions/external.adoc[] - -include::{chapters}layers.adoc[] - -include::{chapters}extensions/VK_KHR_debug_utils.adoc[] - -include::{chapters}depth.adoc[] -include::{chapters}extensions/VK_KHR_sampler_ycbcr_conversion.adoc[] - -include::{chapters}versions.adoc[] - -include::{chapters}extensions/VK_EXT_inline_uniform_block.adoc[] - -include::{chapters}extensions/VK_KHR_descriptor_update_template.adoc[] - -include::{chapters}high_level_shader_language_comparison.adoc[] - -include::{chapters}extensions/VK_KHR_imageless_framebuffer.adoc[] - -include::{chapters}primitive_topology.adoc[] -include::{chapters}extensions/VK_KHR_shader_subgroup_uniform_control_flow.adoc[] - -include::{chapters}storage_image_and_texel_buffers.adoc[] - -include::{chapters}extensions/VK_EXT_descriptor_indexing.adoc[] - -include::{chapters}extensions/device_groups.adoc[] - -include::{chapters}synchronization.adoc[] - -include::{chapters}extensions/shader_features.adoc[] - -include::{chapters}mapping_data_to_shaders.adoc[] -include::{chapters}extensions/VK_EXT_memory_priority.adoc[] - -include::{chapters}what_vulkan_can_do.adoc[] - -include::{chapters}extensions/cleanup.adoc[] - -include::{chapters}subgroups.adoc[] - -include::{chapters}storage_image_and_texel_buffers.adoc[] - -include::{chapters}vertex_input_data_processing.adoc[] - -include::{chapters}descriptor_arrays.adoc[] - -include::{chapters}descriptor_dynamic_offset.adoc[] - -include::{chapters}descriptor_buffer.adoc[] - -include::{chapters}location_component_interface.adoc[] - -include::{chapters}push_constants.adoc[] - -include::{chapters}ways_to_provide_spirv.adoc[] - -include::{chapters}robustness.adoc[] - -include::{chapters}dynamic_state.adoc[] - -include::{chapters}dynamic_state_map.adoc[] - -include::{chapters}subgroups.adoc[] - -include::{chapters}shader_memory_layout.adoc[] - -include::{chapters}atomics.adoc[] - -include::{chapters}image_copies.adoc[] - -include::{chapters}common_pitfalls.adoc[] - -include::{chapters}hlsl.adoc[] - -include::{chapters}high_level_shader_language_comparison.adoc[] - -= When and Why to use Extensions - -[NOTE] -==== -These are supplemental references for the various Vulkan Extensions. Please consult the Vulkan Spec for further details on any extension -==== - -// Switch imagesdir for chapters/extensions/ includes so they can also load as single pages -// :imagesdir: chapters/images/extensions - -include::{chapters}extensions/cleanup.adoc[] - -include::{chapters}extensions/device_groups.adoc[] - -include::{chapters}extensions/external.adoc[] - -include::{chapters}extensions/ray_tracing.adoc[] - -include::{chapters}extensions/shader_features.adoc[] - -include::{chapters}extensions/translation_layer_extensions.adoc[] - -include::{chapters}extensions/VK_EXT_descriptor_indexing.adoc[] - -include::{chapters}extensions/VK_EXT_inline_uniform_block.adoc[] - -include::{chapters}extensions/VK_EXT_memory_priority.adoc[] - -include::{chapters}extensions/VK_KHR_descriptor_update_template.adoc[] - -include::{chapters}extensions/VK_KHR_draw_indirect_count.adoc[] - -include::{chapters}extensions/VK_KHR_image_format_list.adoc[] - -include::{chapters}extensions/VK_KHR_imageless_framebuffer.adoc[] - -include::{chapters}extensions/VK_KHR_sampler_ycbcr_conversion.adoc[] - -include::{chapters}extensions/VK_KHR_shader_subgroup_uniform_control_flow.adoc[] - -include::{chapters}extensions/VK_KHR_debug_utils.adoc[] - -= link:CONTRIBUTING.adoc[Contributing] - -= link:LICENSE[License] - -= link:CODE_OF_CONDUCT.adoc[Code of conduct] diff --git a/lang/jp/README-jp.adoc b/lang/jp/README-jp.adoc index 1adca87..716cfbb 100644 --- a/lang/jp/README-jp.adoc +++ b/lang/jp/README-jp.adoc @@ -21,11 +21,6 @@ image::../../images/khronos_logo.png[Khronos logo] Vulkan Guide は、開発者が Vulkan の世界へ足を踏み出すための手助けをするものです。このガイドは気軽に読める内容を目指しており、知りたいトピックに対して参考になるさまざまな資料を紹介します。ここには、Vulkan の多くのニュアンスに対する理解を促すための情報が記載されています。 -[NOTE] -==== -Vulkan Guide は、`asciidoctor guide.adoc` を使って1つのページとしてビルドできます。 -==== - :leveloffset: 1 = 概要 diff --git a/lang/kor/README-kor.adoc b/lang/kor/README-kor.adoc index 279ab31..b27e6c7 100644 --- a/lang/kor/README-kor.adoc +++ b/lang/kor/README-kor.adoc @@ -21,10 +21,6 @@ image::../../images/khronos_logo.png[Khronos logo] Vulkan Guide는 개발자가 Vulkan의 세계를 시작하는 데 도움을 주기 위해 작성되었습니다. 이 가이드는 개발자가 원하는 내용에 따라 다른 유용한 링크로 연결되는 가벼운 읽기를 목표로 합니다. 모든 정보는 Vulkan의 다양한 뉘앙스를 더 잘 이해할 수 있도록 돕기 위한 것입니다. -[NOTE] -==== -Vulkan Guide는 `asciidoctor guide.adoc` 를 사용해 하나의 페이지로서 빌드할 수 있습니다. -==== [NOTE] ==== Vulkan에서 사용하는 특수한 용어에 대한 혼란을 막기 위해 명령과 연관된 경우 번역하지 않고 용어 발음을 그대로 사용하였습니다. +