Add toml documentation (#506)

Signed-off-by: Olblak <me@olblak.com> Signed-off-by: Olblak <me@olblak.com>
updatecli · Sep 28, 2022 · 4812cd0 · 4812cd0
1 parent a0edbd6
commit 4812cd0
Show file tree

Hide file tree

Showing 3 changed files with 118 additions and 0 deletions.
diff --git a/assets/code_example/docs/plugins/resources/toml/updatecli.d/default.yaml b/assets/code_example/docs/plugins/resources/toml/updatecli.d/default.yaml
@@ -0,0 +1,27 @@
+name: Basic Json Example
+
+sources:
+  local:
+    name: Get value from toml
+    kind: toml
+    spec:
+      file: pkg/plugins/resources/toml/testdata/data.toml
+      key: owner.firstName
+
+conditions:
+  local:
+    name: Test value from toml
+    kind: toml
+    spec:
+      file: pkg/plugins/resources/toml/testdata/data.toml
+      key: owner.firstName
+
+targets:
+  local:
+    name: Ensure owner.firstName is set to John
+    kind: toml
+    spec:
+      file: pkg/plugins/resources/toml/testdata/data.toml
+      key: owner.firstName
+      value: John
+
diff --git a/assets/code_example/docs/plugins/resources/toml/updatecli.d/fallback.yaml b/assets/code_example/docs/plugins/resources/toml/updatecli.d/fallback.yaml
@@ -0,0 +1,22 @@
+sources:
+    hugo:
+        name: Get latest HUGO version
+        kind: githubrelease
+        transformers:
+            - trimprefix: v
+        spec:
+            owner: gohugoio
+            repository: hugo
+            token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'
+            username: '{{ requiredEnv "UPDATECLI_GITHUB_ACTOR" }}'
+
+targets:
+    netlify:
+        name: Update Hugo version used on Netlify
+        kind: file
+        spec:
+            file: netlify.toml
+            matchpattern: HUGO_VERSION = "(.*)"
+            replacepattern: HUGO_VERSION = "{{ source "hugo" }}"
+        scmid: default
+        sourceid: hugo
diff --git a/content/en/docs/plugins/resource/toml.adoc b/content/en/docs/plugins/resource/toml.adoc
@@ -0,0 +1,69 @@
+---
+title: "TOML"
+description: "Manipulate Toml information"
+lead: "kind: toml"
+date: 2021-09-24T19:19:01+02:00
+draft: false
+images: []
+menu:
+  docs:
+    parent: "plugin-resource"
+toc: true
+plugins:
+  - source
+  - condition
+  - target
+---
+// <!-- Required for asciidoctor -->
+:toc:
+// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
+:toclevels: 4
+
+[cols="1^,1^,1^",options=header]
+|===
+| source | condition | target
+| &#10004; | &#10004; | &#10004;
+|===
+
+== Description
+
+**source**
+
+The TOML "source" retrieves an information from a TOML file.
+
+**condition**
+
+The TOML "condition" tests that an information exist in a TOML file.
+
+**target**
+
+The TOML "target" ensures that a TOML file content a specific value at specific location.
+
+== Parameters
+
+{{< resourceparameters "sources" "toml" >}}
+
+=== Xpath
+
+Under construction, some help would be need to document common jsonpath query that work with Updatecli
+https://www.w3.org/TR/1999/REC-xpath-19991116/
+
+== Example
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/resources/toml/updatecli.d/default.yaml">}}
+----
+
+== Important
+
+The library used to manipulate TOML files, drops comments. More information is available on
+link:https://github.com/TomWright/dasel/issues/178[tomwright/dasel#178]. Until we find a solution, a potential workaround is to use the resource `file` like in the following example:
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/resources/toml/updatecli.d/fallback.yaml">}}
+----
+