Metadata-Version: 2.1
Name: yamlex
Version: 0.2.1
Summary: Command-line tool to simplify work with Dynatrace Extensions with big YAML
Home-page: https://github.com/dynatrace-extensions/dt-extensions-yaml-assembler
License: Apache-2.0
Keywords: dynatrace,cli,extensions
Author: Vagiz Duseev
Author-email: vagiz.duseev@dynatrace.com
Maintainer: Vagiz Duseev
Maintainer-email: vagiz.duseev@dynatrace.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: jsonschema (>=4.7,<5.0)
Requires-Dist: rich (>=13.7.1,<14.0.0)
Requires-Dist: ruamel-yaml (>=0.18.6,<0.19.0)
Requires-Dist: typer (>=0.6,<0.7)
Requires-Dist: typing-extensions (>=4.10.0,<5.0.0)
Requires-Dist: wheel (>=0.37,<0.38)
Project-URL: Documentation, https://github.com/dynatrace-extensions/dt-extensions-yaml-assembler
Project-URL: Repository, https://github.com/dynatrace-extensions/dt-extensions-yamlex
Description-Content-Type: text/markdown

# Yamlex

The `yamlex` command-line tool is here to assist you in working with
an oversized `extension.yaml`, when developing a Dynatrace 2.0 Extension.

It can `split` your original `extension.yaml` into carefully structured 
parts, which are easier to work with. It can then `join` the individual
parts together, assembling the `extension.yaml` back from them.

The Extension Framework still only cares about the final assembled
`extension.yaml`. Any extension would be considered invalid without it.
However, it is recommended to still commit both the individual parts and
the assembled `extension.yaml` file into the code repository of your
extension, because individual parts are your "code" and the assembled 
file is your artifact. 

With `yamlex`, your development workflow changes in such a way that
you only modify the individual parts and never really touch the artificial 
`extension.yaml`. Before you build the extension, you run `yamlex join`
to assemble the parts into the main file.

## Installation

```shell
pip install yamlex
```

## Usage

### (optional) Enable YAML validation and auto-completion 

By invoking `yamlex map` you can map the extension JSON scema files to the future YAML parts of the split 
`extension.yaml`. This will ensure proper validation and auto-completion 
for each and every part and not just for the `extension.yaml`.

Before you execute the `map` command, make sure relevant JSON schema
files for extensions are downloaded and are placed in the right folder.
By default, `yamlex` expects the relevant schema folder to be placed in
the current directory under the `schema/` name.

```shell
yamlex map
```

If it's located somewhere else, you can point `yamlex` to it using the
`--json <path_to_schema>` option.

```shell
yamlex map --json <path_to_schema> 
```

### (optional) Split the `extension.yaml`

This command will split the `extension.yaml` into individual parts.
It is useful when you only just start using `yamlex` with an existing
extension.

```shell
yamlex split
```

When you first split the original file, make sure you create a base
file called `extension.base.yaml` in the extension directory, right
where the `extension.yaml` is supposed to be.

The `extension.base.yaml` must contain all the basic metadata for the extension. Example:

```yaml
name: custom:com.dynatrace.extension.postgres-data
version: 1.1.3
minDynatraceVersion: 1.279.0
author:
  name: Dynatrace
  
dashboards:
  - path: dashboards/overview_dashboard.json
```

### Assemble `extension.yaml` from parts

```shell
yamlex join
```

When assembling, the `join` command will avoid overwriting a manually
created `extension.yaml` file. The way it detects that the file is
manually created is by checking whether the file contains the following
comment: *generated by yamlex*.

In order to overwrite this safety check, you can launch the `join`
command with the `--force` flag.

If you want to assemble the file into the different path, you can
specify that using the `--output` option:

```shell
yamlex join --output <path_to_final_file>
```

