znrun-project-generator 1.0.0
A text templating tool Rohde & Schwarz ZNrun project generation
Requires Python: >=3.4, <4
Keywords: Rohde & Schwarz,R&S,ZNrun,Vector Network Analyzer

# ZNrun Project Generator

ZNrun Project Generator is a text templating tool that transforms `YAML` input data and `Jinja2` XML text templates into a ZNrun project.

ZNrun requires XML project files as input. These files are complicated and hard to understand and generate. ZNrun Project Generator aims to make this as simple and straightforward as possible.

## Requirements

- Python 3.4+ (uses pathlib extensively)
- [Jinja2](https://github.com/pallets/jinja)
- [ruamel.yaml](https://sourceforge.net/projects/ruamel-yaml/)

## Project Templates

ZNrun Project Generator takes Project Templates as input.

Project Templates consist of three parts, reflected in the directory structure shown below:

```comment
project/
  data/
  template/
  metadata.yaml
```

All three parts are optional, and are explained in greater detail below.

### Data

`data/` is a YAML file structure that is read and provided as input to the Template.

This is easiest to understand with an example.

Given the following YAML file structure:

```comment
project/
  data/
    key1.yaml
    key2.yaml
    ...
```

Text template files will have access to the following data structure:

```python
{
  'key1': yaml.safe_load('project/data/key1.yaml')
  'key2': yaml.safe_load('project/data/key2.yaml')
  # ...
}
```

### Template

`Template` is a file structure that is processed according to a set of rules that are inspired by [`Ruby on Rails Layouts and Rendering`](https://guides.rubyonrails.org/layouts_and_rendering.html).

The rules for transformation are as follows:

- File names and relative directory structure are preserved *except where noted below*.
- Files that are prefixed with `_` are considered includes and are not processed to build output.
- The `project_name/` folder is renamed to `{{ data['project']['name'] }}/`
- The `project_name.znwbf.jinja2` file is renamed to `{{ data['project']['name'] }}.znwbf`
- Files that do not have extension `.jinja2` are copied to build output as-is.
- Files without a `_` prefix that have extension `.jinja2` are processed as a `Jinja2` template and written to the build output.

## Metadata

Metadata provides for *[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)* Data and Template reuse.

### File Structure

This is done by first defining a Metadata file structure. This structure should be external to the individual projects.

The `templates` subfolder, if present, is specially handled. Each subfolder is made available as a `Jinja2` Project Template for reference in project `metadata.yaml`.

All other subfolders are read as `YAML` data structures.

For example, given the following metadata:

```
metadata/
  templates/
    kr4-cable-test/
  stimulus/
    ieee-802.3ck
```

... the following `metadata.yaml` file will provide the `metadata/stimulus/ieee-802.3ck.yaml` stimulus data to the  `metadata/templates/kr4-cable-test/` project template:

```YAML
template: kr4-cable-test
stimulus: ieee-802.3ck
```

## References

### Jinja2 Text Templating

For more information on how to use Jinja2 Templates, see [Jinja2 Template Designer Documentation](https://jinja.palletsprojects.com/en/2.11.x/templates/)