Samples documentation fixes and enhanchements (KhronosGroup#905)

* Include related extension list instead of linking to it (link was broken anyway)

* Different content depending on generator

* Reworking things

List of examples in subfolder readme
This is then included in tioplevel sample listing instead
Paths need to be adjusted via attributes to make it work for both

* Fix links to ray tracing samples KhronosGroup#903

* Fix xref paths

Makes xrefs works both on the separate sample list as well as the page including it
Refs KhronosGroup#898

* Fix links to ray tracing samples

Refs KhronosGroup#903

* Add samples listing to docs navigation

* Move api samples listing into separate readme

Include in main listing

* Added readme for general samples folder

Include in main listing

* Add samples listing to docs navigation

* Move tooling and performance samples listing into separate readme

Include in main listing

* Update pull request template

* Remove link to pull request template

Didn't work in github either, and makes no sense
People will see that template when they actually do a PR against the repo

* Add link to framework components

Fix linkage for framework core

* Fix link to debug utils sample

* Add a stub readme for the docs folder

* Fix broken links

Refs KhronosGroup#824

* Fix broken image links

Refs KhronosGroup#824

* Removed unnecessary paragraph

PRs are created via github anyway, and this automatically uses the PR template
No need to mention it explicitly

* Fix copyright

* Fix copyright (again...)

* Fix typo

CONTRIBUTING.adoc

@@ -1,5 +1,5 @@
 ////
-- Copyright (c) 2019-2023, Arm Limited and Contributors
+- Copyright (c) 2019-2024, Arm Limited and Contributors
 -
 - SPDX-License-Identifier: Apache-2.0
 -
@@ -134,11 +134,7 @@ Ensure that you are using clang-format 8.
 . Make sure the sample code builds and runs on Windows, Linux, macOS and Android.
 If you cannot verify on all these target platforms, please note platform restrictions in the sample's README.
 . Verify the sample against a recent version of the Vulkan validation layers, either built from source or from the most recent available Vulkan SDK.
-. Submit a <<creating-a-pull-request,pull request>> for the contribution, including electronically signing the Khronos Contributor License Agreement (CLA) for the repository using CLA-Assistant.
-
-== Creating a Pull Request
-
-When you create your pull request, ensure the description is created with xref:docs/pull_request_template.md[this template], and then fill out the relative information.
+. Submit a pull request via github for the contribution, including electronically signing the Khronos Contributor License Agreement (CLA) for the repository using CLA-Assistant.
 
 == Code Reviews
 

antora/modules/ROOT/nav.adoc

@@ -1,6 +1,6 @@
 ////
-- Copyright (c) 2024, Holochip Inc
-- Copyright (c) 2024, Sascha Willems
+- Copyright (c) 2023, Holochip Inc
+- Copyright (c) 2023-2024, Sascha Willems
 -
 - SPDX-License-Identifier: Apache-2.0
 -
@@ -17,8 +17,10 @@
 - limitations under the License.
 -
 ////
+* xref:samples/README.adoc[Samples overview]
 * xref:samples/vulkan_basics.adoc[Vulkan basics]
 * xref:framework/README.adoc[Sample framework]
+** xref:components/README.adoc[Framework components]
 * xref:samples/api/README.adoc[Api usage samples]
 ** xref:samples/api/compute_nbody/README.adoc[Compute N-body]
 *** xref:samples/api/hpp_compute_nbody/README.adoc[Compute N-body (Vulkan-Hpp)]
@@ -71,8 +73,8 @@
 ** xref:samples/extensions/open_gl_interop/README.adoc[OpenGL interop]
 ** xref:samples/extensions/portability/README.adoc[Portability]
 ** xref:samples/extensions/push_descriptors/README.adoc[Push descriptors]
-** xref:samples/extensions/raytracing_basic/README.adoc[Raytracing basic]
-** xref:samples/extensions/raytracing_extended/README.adoc[Raytracing extended]
+** xref:samples/extensions/ray_tracing_basic/README.adoc[Raytracing basic]
+** xref:samples/extensions/ray_tracing_extended/README.adoc[Raytracing extended]
 ** xref:samples/extensions/ray_queries/README.adoc[Ray queries]
 ** xref:samples/extensions/ray_tracing_reflection/README.adoc[Ray tracing reflection]
 ** xref:samples/extensions/shader_object/README.adoc[Shader Object]

components/README.adoc

@@ -1,5 +1,6 @@
 ////
-- Copyright (c) 2023, Thomas Atkinson
+- Copyright (c) 2023-2024, Thomas Atkinson
+- Copyright (c) 2024, The Khronos Group
 -
 - SPDX-License-Identifier: Apache-2.0
 -
@@ -31,7 +32,7 @@ These interfaces are defined in `components/core`.
 *Core* is the only component which does not follow the component pattern in its entirety.
 The only major difference between core and other components is the header prefix used is `core/<sub_dir>` instead of `components/core/<sub_dir>`.
 
-See xref:core/README.adoc[core documentation] for more information.
+See xref:./core/README.adoc[core documentation] for more information.
 
 == Create a new component
 

docs/README.adoc

@@ -0,0 +1,21 @@
+////
+- Copyright (c) 2024, Sascha Willems
+-
+- SPDX-License-Identifier: Apache-2.0
+-
+- Licensed under the Apache License, Version 2.0 the "License";
+- you may not use this file except in compliance with the License.
+- You may obtain a copy of the License at
+-
+-     http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-
+////
+= General documentation
+
+This folder contains documentation on general usage of the samples.

docs/build.adoc

@@ -1,5 +1,5 @@
 ////
-- Copyright (c) 2019-2023, Arm Limited and Contributors
+- Copyright (c) 2019-2024, Arm Limited and Contributors
 -
 - SPDX-License-Identifier: Apache-2.0
 -
@@ -82,7 +82,7 @@ Enable https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/sy
 
 Enable VK_EXT_debug_utils or VK_EXT_debug_marker, if supported.
 This enables debug names for Vulkan objects, and markers/labels in command buffers.
-+ See the xref:samples/extensions/debug_utils/debug_utils_tutorial.adoc[debug utils sample] for more information.
++ See the xref:../samples/extensions/debug_utils/README.adoc[debug utils sample] for more information.
 
 *Default:* `ON`
 

docs/pull_request_template.md

@@ -31,6 +31,6 @@ If your PR contains a new or modified sample, these further checks must be carri
 - [ ] If the sample is vendor-specific, I have [tagged it appropriately](https://github.com/KhronosGroup/Vulkan-Samples/tree/main/CONTRIBUTING.adoc#General-Requirements)
 - [ ] I have stated on what implementation the sample has been tested so that others can test on different implementations and platforms
 - [ ] Any dependent assets have been merged and published in downstream modules
-- [ ] For new samples, I have added a paragraph with a summary to the appropriate chapter in the [samples readme](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/samples/README.adoc)
+- [ ] For new samples, I have added a paragraph with a summary to the appropriate chapter in the readme of the folder that the sample belongs to [e.g. api samples readme](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/samples/api/README.adoc)
 - [ ] For new samples, I have added a tutorial README.md file to guide users through what they need to know to implement code using this feature. For example, see [conditional_rendering](https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/extensions/conditional_rendering)
 - [ ] For new samples, I have added a link to the [Antora navigation](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/antora/modules/ROOT/nav.adoc) so that the sample will be listed at the Vulkan documentation site