From 5dbffba055a3ece1695f377e6d5aa4b8163e9fb2 Mon Sep 17 00:00:00 2001
From: Louis Capitanchik <contact@louiscap.co>
Date: Wed, 22 Feb 2023 22:31:14 +0000
Subject: [PATCH] Update pipeline file format docs
---
docs/pipelines/file_format.md | 61 +++++++++++++++++++++++++++++++
docs/pipelines/getting_started.md | 2 +
2 files changed, 63 insertions(+)
diff --git a/docs/pipelines/file_format.md b/docs/pipelines/file_format.md
index 9a399e9..9c2d4d9 100644
--- a/docs/pipelines/file_format.md
+++ b/docs/pipelines/file_format.md
@@ -1,3 +1,64 @@
# Pipeline.toml
## _WIP_
+Pipeline toml files can be incredibly concise by using many bits of shortcut syntax. Be sure to familiarise yourself
+with the [TOML language](https://toml.io/en/) to get the most from this.
+
+Pipelines have three sections, defined in up to two locations: An input, an output, and a series of actions that will
+be executed in order to transform one to the other.
+
+```toml
+# # #
+# Create reusable sets of actions in the "refs" map that can be used for multiple assets. Pipeline actions can also
+# be defined inline, but you will typically need to use a pipeline more than once.
+# # #
+[[refs.flip_and_scale.actions]]
+command = "Flip"
+params = { direction = "horizontal" }
+
+[[refs.flip_and_scale.actions]]
+command = "Scale"
+params = { factor = 2.0 }
+
+[[refs.rotate.actions]]
+command = "Rotate"
+params = { amount = "one" }
+
+# There are three ways to write the input & output section of a pipeline.
+
+# 1) You can defined everything inline in the pipelines array
+[[pipelines]]
+input_path = "./some_sprites.png"
+output_path = "../built/some_sprites.png"
+actions = [
+ { command = "Rotate", params = { amount = "one" } }
+]
+
+# 2) You can reference a preset of actions defined in the "refs" table
+[[pipelines]]
+input_path = "./some_sprites.png"
+output_path = "../built/some_sprites.png"
+reference = "flip_and_scale"
+
+# 3) You can use a reference alongside a glob pattern to target multiple assets
+[[pipelines]]
+pattern = "./creatures/*.png"
+output_dir = "../built/creatures"
+reference = "rotate"
+
+```
+
+Another way to write the reference section of the above example would be:
+
+```toml
+[refs.flip_and_scale]
+actions = [
+ { command = "Flip", params = { direction = "horizontal" } },
+ { command = "Scale", params = { factor = 2.0 } }
+]
+
+[refs.rotate]
+actions = [
+ { command = "Rotate", params = { amount = "one" } }
+]
+```
\ No newline at end of file
diff --git a/docs/pipelines/getting_started.md b/docs/pipelines/getting_started.md
index 47af354..ecc6592 100644
--- a/docs/pipelines/getting_started.md
+++ b/docs/pipelines/getting_started.md
@@ -1,6 +1,8 @@
# Getting Started With Pipelines
## _WIP_
+[TOML file layout](file_format.md)
+
### Execution Model
### Data Flow
\ No newline at end of file
--
GitLab