From e876c053387870ec271d9cfce532712e06e5612d Mon Sep 17 00:00:00 2001 From: Alejandro Jose Leiva Palomo Date: Tue, 24 Oct 2023 16:32:43 -0600 Subject: [PATCH 1/2] docs: updating vtt documentation for trestle author docs Signed-off-by: Alejandro Jose Leiva Palomo --- docs/trestle_author.md | 55 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/trestle_author.md b/docs/trestle_author.md index db3f94721..9b5174528 100644 --- a/docs/trestle_author.md +++ b/docs/trestle_author.md @@ -296,6 +296,61 @@ Running `trestle author docs validate -tn docs_task -gh="Governed section"` will - If `--template-version 1.0.0` (`-tv`) is passed the header field `x-trestle-template-version` will be ignored and document will be forcefully validated against template of version `1.0.0`. Use this for testing purposes _only_ when you need to validate the document against a specific template. By default the template version will be determined based on `x-trestle-template-version` in the document. +### Validating the documents against different templates + +Validation against multiple templates can be done when there is an scenario where you have multiple templates that will have multiple instances. In this particular case you can have a 1:1 relationship between the template and the instance document you are creating out of it, so validation can be performed based on template type and version of that particular template defined in headers. + +For that to happen you will need to provide your template with the following parameter at the yaml header level, matching the type of template to be implemented so the validation can occur: + +> x-trestle-template-type: insert_template_type_here + +Please, take into consideration that for the validation to happen you will also need to provide each instance document in the task folder a field called `x-trestle-template-type: insert_template_type_here` in the yaml header matching with the template name. + +```yaml +--- +authors: tmp +owner: tmp +valid: + from: null + to: null +x-trestle-template-type: insert_template_type_here +--- +``` + +With that, you will be able to create more than 1 instance document per template and give the instance the desired name. + +For instance, let´s consider the next folder structure: + +```text +trestle_root +┣ .trestle +┃ ┣ author +┃ ┃ ┣ my_task_2 +┃ ┃ ┃ ┣ 0.0.1 +┃ ┃ ┃ ┃ ┣ a_template.md +┃ ┃ ┃ ┃ ┣ another_template.md +┃ ┃ ┃ ┃ ┗ arhitecture.drawio +┃ ┗ config.ini + +trestle_root + ┣ .trestle + ┣ my_task_2 + ┃ ┣ sample_folder_0 + ┃ ┃ ┣ a_template_1.md + ┃ ┃ ┣ a_template_2.md + ┃ ┃ ┣ arhitecture_1.drawio + ┃ ┃ ┗ another_template_123.md + +``` + +If you noticed, names are no longer needed to match with exact template names, and that´s because validation will run through `x-trestle-template-type` field defined at the instance header, not through the name. + +To validate the documents against their respective templates using `x-trestle-template-type`, run: + +> trestle author docs validate -tn my_task_name -vtt + +Now, `-vtt` stands for validate template type. Validate template type option will provide you the ability to have more than 1 instance per template validated. +
From 33ff5d5f4de3a13e5a16778a1fa3b43d46b30916 Mon Sep 17 00:00:00 2001 From: Alejandro Jose Leiva Palomo Date: Wed, 25 Oct 2023 11:16:19 -0600 Subject: [PATCH 2/2] fix: correct wording Signed-off-by: Alejandro Jose Leiva Palomo --- docs/trestle_author.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/trestle_author.md b/docs/trestle_author.md index 9b5174528..e02610a89 100644 --- a/docs/trestle_author.md +++ b/docs/trestle_author.md @@ -298,9 +298,9 @@ Running `trestle author docs validate -tn docs_task -gh="Governed section"` will ### Validating the documents against different templates -Validation against multiple templates can be done when there is an scenario where you have multiple templates that will have multiple instances. In this particular case you can have a 1:1 relationship between the template and the instance document you are creating out of it, so validation can be performed based on template type and version of that particular template defined in headers. +Validation against multiple templates can be done when there is a scenario where you have multiple templates that will have multiple instances. In this particular case you can have a 1:1 relationship between the template and the instance document you are creating out of it, so validation can be performed based on template type and version of that particular template defined in headers. -For that to happen you will need to provide your template with the following parameter at the yaml header level, matching the type of template to be implemented so the validation can occur: +For that to happen you will need to provide your template with the following parameter at the yaml header level, matching the type of template to be implemented so that the validation can occur: > x-trestle-template-type: insert_template_type_here