Remove legacy guide.adoc (#345)

Author: spencer-lunarg

.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:

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.
 

Makefile

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

README.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