docs: fix info about %include for sample files (#3246)

Signed-off-by: Meg McRoberts <[email protected]> Signed-off-by: Moritz Wiesinger <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]>
keptn · Mar 21, 2024 · bc1ead5 · bc1ead5
1 parent 2adf738
commit bc1ead5
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 10 deletions.
diff --git a/docs/docs/contribute/docs/code-docs.md b/docs/docs/contribute/docs/code-docs.md
@@ -19,7 +19,7 @@ The following documents document the language:
 Markdown supports many variants and the build tools we use
 impose a few special requirements that are discussed here.
 
-## Frontmatter requirements
+## Front matter requirements
 
 The top of each documentation source file should look like:
 
@@ -65,6 +65,33 @@ as in:
 <!-- This is a comment -->
 ```
 
+## Displaying sample files
+
+Most Keptn configuration is implemented as YAML files
+that define a resource
+so displaying an example file is very useful.
+However, the file content should not be put directly into your doc source.
+Instead, the sample file is put into an `assets` directory
+and then "included" in your file.
+This keeps the documentation source cleaner
+and enables us to run tests to ensure that the YAML file is valid
+as Keptn evolves.
+
+To implement this:
+
+1. Either identify the file you want to include
+   in the `assets` directory next to your documentation file
+   or create your sample YAML file in that tree,
+   giving it an appropriate name, including the `.yaml` suffix.
+
+2. Use the `include <file-path>` shortcode
+   to include this file in your documentation source inside a code block.
+   For example:
+
+      ```md
+      {% /* include "../../assets/crd/python-libs.yaml" %}
+      ```
+
 ## Indentation of nested lists and code blocks
 
 Paragraphs and code blocks that are nested under a list item

diff --git a/docs/docs/contribute/docs/contrib-guidelines-docs.md b/docs/docs/contribute/docs/contrib-guidelines-docs.md
@@ -50,15 +50,9 @@ that are relevant only to documentation.
   use the `include <file-path>` shortcode syntax
   (which automatically pulls the current version of the file into your document)
   rather than copying the text.
-  This ensures that, when the sample file is updated,
-  your document is also updated.
-
-    For example, to include the `examples/sample-app/version1/app-pre-deploy-eval.yaml` file,
-    the syntax is:
-
-    ```md
-    {% /* include "examples/sample-app/version-1/app-pre-deploy-eval.yaml" */ %}
-    ```
+  See
+  [Displaying sample files](code-docs.md/#comments)
+  for details.
 
 * `markdownlint` enforces limits on line length.
   Links to other documents are exempted from this limit