Skip to content

Rework the README to explain what the repository contains - #541

Open
gpx1000 wants to merge 1 commit into
KhronosGroup:mainfrom
gpx1000:fix/497-readme-rework
Open

gpx1000 wants to merge 1 commit into
KhronosGroup:mainfrom
gpx1000:fix/497-readme-rework

Conversation

@gpx1000

@gpx1000 gpx1000 commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

link to the online tutorial, fix the broken links, and add local build and preview instructions. Fixes #497.

…e online tutorial, fix the broken links, and add local build and preview instructions. Fixes KhronosGroup#497.
Comment thread README.adoc

It also contains Vulkan usage clarifications, improved synchronization and new content.
* The primary **Khronos Vulkan Tutorial** updates the traditional link:https://vulkan-tutorial.com/[Vulkan Tutorial by Alexander Overvoorde] to use modern Vulkan features and practices.
See link:en/00_Introduction.adoc[the introduction] for a quick start.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be an xref.

Comment thread README.adoc

You will also need to install the Vulkan SDK separately from https://vulkan.lunarg.com/.
The tutorial is written in AsciiDoc and rendered with Antora, so some things that look broken in GitHub's preview, such as missing images or cross-references, are expected.
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for how to preview AsciiDoc in your editor.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be an xref

Comment thread README.adoc
The primary Khronos Vulkan Tutorial is based on the "link:https://vulkan-tutorial.com/[Vulkan Tutorial]" by Alexander Overvoorde and is licensed under link:https://creativecommons.org/licenses/by-sa/4.0/[CC BY-SA 4.0].
Different parts of the repository are under different licenses:
the Arm tutorials are also CC BY-SA 4.0, the Holochip tutorials are link:https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0], and code listings are link:https://creativecommons.org/publicdomain/zero/1.0/[CC0 1.0 Universal] where applicable.
The link:en/00_Introduction.adoc#_attribution[attribution section] of the introduction lists which tutorials are covered by which license, the full license texts are in the `LICENSES` directory, and `REUSE.toml` records which license covers which files.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be an xref

Comment thread README.adoc
Different parts of the repository are under different licenses:
the Arm tutorials are also CC BY-SA 4.0, the Holochip tutorials are link:https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0], and code listings are link:https://creativecommons.org/publicdomain/zero/1.0/[CC0 1.0 Universal] where applicable.
The link:en/00_Introduction.adoc#_attribution[attribution section] of the introduction lists which tutorials are covered by which license, the full license texts are in the `LICENSES` directory, and `REUSE.toml` records which license covers which files.
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for how contributions are licensed.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be an xref

Comment thread README.adoc
Humans have reviewed all content of all tutorials and we welcome feedback.

xref:AI_Assisted_Vulkan/introduction.adoc[LLM-Assistant Vulkan Development] tutorial used for all LLM use in these tutorials and sample code.
The link:en/AI_Assisted_Vulkan/introduction.adoc[LLM-Assistant Vulkan Development] tutorial used for all LLM use in these tutorials and sample code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be an xref.

@iagoCL

iagoCL commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator

Since README.adoc is read directly on GitHub, maybe we should link to the published introduction? That would take readers to the tutorial site, where the navigation and chapter links work correctly.

-link:en/00_Introduction.adoc[the introduction]
+link:https://docs.vulkan.org/tutorial/latest/00_Introduction.html[the introduction]

No strong preference, though

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improvements to the README.adoc

3 participants