From 5d60a6e943b6115aa591db92c76ac2a161c9712f Mon Sep 17 00:00:00 2001 From: Sebastian Schleemilch Date: Mon, 27 Jul 2026 13:16:12 +0200 Subject: [PATCH] feat: documenting `includes` vss-tools feature Signed-off-by: Sebastian Schleemilch --- docs-gen/content/rule_set/branches.md | 22 +++++----- docs-gen/content/rule_set/includes.md | 59 +++++++++++++++++++++------ 2 files changed, 58 insertions(+), 23 deletions(-) diff --git a/docs-gen/content/rule_set/branches.md b/docs-gen/content/rule_set/branches.md index ceffede51..0626b9211 100644 --- a/docs-gen/content/rule_set/branches.md +++ b/docs-gen/content/rule_set/branches.md @@ -15,6 +15,7 @@ Vehicle.Trunk: description: All signals related to the rear trunk aggregate: false ``` + Each data entry has a name, in the example above `Vehicle.Trunk`. VSS use a dot-notated name style where the full path of a branch consists of all parent branches from the root node separated by dots and at the end the name of the current branch. In the standard VSS catalog the root node is called `Vehicle`. @@ -25,18 +26,19 @@ When using `*.vspec` files to define a VSS catalog it is not necessary to give t This is the list of attributes that must be specified for every data entry. -Attribute | Description | Comment --------------|-----------------------------|-------- -`type` | Defines the type of the node. For a branch this must be `branch`. | The default for `type` is `branch`. -`description`| Describes the meaning and content of the branch. Recommended to start with a capital letter and end with a dot (`.`). +| Attribute | Description | Comment | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| `type` | Defines the type of the node. For a branch this must be `branch`. | The default for `type` is `branch`. | +| `description` | Describes the meaning and content of the branch. Recommended starting with a capital letter and end with a dot (`.`). | ## Optional Data Entry Attributes -In additon to the mandatory attributes some optional attributes have been defined. +In addition to the mandatory attributes some optional attributes have been defined. There may be additional constraints on their usage not specified in the table below. -Attribute | Description | Comment --------------|-----------------------------|-------- -`comment` | A comment can be used to provide additional informal information on a branch. This could include background information on the rationale for the branch, references to related branches, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). | *since version 3.0* -`instances` | For specifying that multiple instances of this branch exist, for more information see documentation on [instances](/vehicle_signal_specification/rule_set/instances/). -`aggregate` | Defines whether or not this branch is an aggregate. If not defined, this defaults to ```false```. An aggregate is a collection of signals that make sense to handle together in a system. A typical example could be GNSS location, where latitude and longitude make sense to read and write together. This is supposed to be deployment and tool specific, and for that reason no branches are aggregates by default in VSS. For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for individual instances, i.e. signals for different instances can be handled separately. +| Attribute | Description | Comment | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| `comment` | A comment can be used to provide additional informal information on a branch. This could include background information on the rationale for the branch, references to related branches, standards and similar. Recommended to start with a capital letter and end with a dot (`.`). | _since version 3.0_ | +| `instances` | For specifying that multiple instances of this branch exist, for more information see documentation on [instances](/vehicle_signal_specification/rule_set/instances/). | +| `aggregate` | Defines whether this branch is an aggregate. If not defined, this defaults to `false`. An aggregate is a collection of signals that make sense to handle together in a system. A typical example could be GNSS location, where latitude and longitude make sense to read and write together. This is supposed to be deployment and tool specific, and for that reason no branches are aggregates by default in VSS. For branches that both have `instances` defined and `aggregate: true`, then aggregate refers to the signals for individual instances, i.e. signals for different instances can be handled separately. | +| `includes` | A list of files which signals to include below this branch. See [includes](../includes/) for details | diff --git a/docs-gen/content/rule_set/includes.md b/docs-gen/content/rule_set/includes.md index 32d781a8c..cdd62af0b 100644 --- a/docs-gen/content/rule_set/includes.md +++ b/docs-gen/content/rule_set/includes.md @@ -4,7 +4,17 @@ date: 2019-08-04T12:59:44+02:00 weight: 6 --- -An include directive in a vspec file will read the file it refers to and the +Includes can be defined in two different ways. + +When omitting the file extension, we will search all include paths for the file candidates: + +- `.vspec` +- `.yaml` +- `.yml` + +## Directive + +An include directive in a `vspec` file will read the file it refers to and the contents of that file will be inserted into the current buffer in place of the include directive. The included file will, in its turn, be scanned for include directives to be replaced, effectively forming a tree of included @@ -13,18 +23,19 @@ files. See Fig 6 for an example of such a tree. ![Include directive](/vehicle_signal_specification/images/include_directives.png)
-*Fig 6. Include directives* - +_Fig 6. Include directives_ The include directive has the following format: - #include [prefix] +``` +#include [prefix] +``` -The `````` part specifies the path, relative to the file with the ```#include``` directive, to the vspec file to replace the directive with. +The `` part specifies the path, relative to the file with the `#include` directive, to the vspec file to replace the directive with. Additionally, include paths to search for the file can be added when using `vss-tools` using the `-I/--include-dirs`. The order of include paths to be searched is first the relative path of the vspec specifying the include and then given include paths in the given order. -The optional ```[prefix]``` specifies a branch name to be +The optional `[prefix]` specifies a branch name to be prepended to all signal entries in the included file. This allows a vspec file to be reused multiple times by different files, each file specifying their own branch to attach the included file to. @@ -33,16 +44,16 @@ An example of an include directive is: #include doors.vpsec chassis.doors -The ```door.vspec``` section specifies the file to include. +The `door.vspec` section specifies the file to include. -The ```chassis.doors``` section specifies that all signal entries in ```door.vspec``` should have their names prefixed with ```chassis.doors```. +The `chassis.doors` section specifies that all signal entries in `door.vspec` should have their names prefixed with `chassis.doors`. If an included vspec file has branch or signal specifications that have already been defined prior to the included file, the new specifications in the included file will override the previous specifications. +### REUSING SIGNAL TREES -## REUSING SIGNAL TREES Complete subtrees of signals can be reused by including them multiple times, attaching them to different branches each time they are included. @@ -51,10 +62,32 @@ An example is given in Fig 7 where a generic door signal specification is included four times to describe all doors in the vehicle. ![Include directive](/vehicle_signal_specification/images/spec_file_reuse.png)
-*Fig 7. Reusing signal trees* +_Fig 7. Reusing signal trees_ -The ```door.vspec``` file is included four times by the master ```root.vspec``` file. -The signals of ```door.vspec```, ```Locked```, ```WinPos```, and ```Open``` are attached +The `door.vspec` file is included four times by the master `root.vspec` file. +The signals of `door.vspec`, `Locked`, `WinPos`, and `Open` are attached on the front left and right doors of row 1 (front) and row 2 (back). -If ```door.vspec``` is changed, the changes will be propagated to all four doors. +If `door.vspec` is changed, the changes will be propagated to all four doors. + +## Property + +Alternatively, includes can be defined directly for the `type: branch` node: + +```yaml +Vehicle.Cabin: + type: branch + description: Cabin + includes: + - Door +``` + +That's equivalent to the following: + +```yaml +Vehicle.Cabin: + type: branch + description: Cabin + +#include Door Vehicle.Cabin +```