Skip to content

feat: documenting includes vss-tools feature #929

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sschleemilch wants to merge 1 commit into
base: master
Choose a base branch
from
+58 −23
Open

feat: documenting includes vss-tools feature #929

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions docs-gen/content/rule_set/branches.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand All @@ -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 |
59 changes: 46 additions & 13 deletions docs-gen/content/rule_set/includes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

- `<filename>.vspec`
- `<filename>.yaml`
- `<filename>.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
Expand All @@ -13,18 +23,19 @@ files.
See Fig 6 for an example of such a tree.

![Include directive](/vehicle_signal_specification/images/include_directives.png)<br>
*Fig 6. Include directives*

_Fig 6. Include directives_

The include directive has the following format:

#include <filename> [prefix]
```
#include <filename> [prefix]
```

The ```<filename>``` part specifies the path, relative to the file with the ```#include``` directive, to the vspec file to replace the directive with.
The `<filename>` 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.
Expand All @@ -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.
Expand All @@ -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)<br>
*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
```
Loading