From 5ce87cc2ede576af5d6a9b21ee203573214deea5 Mon Sep 17 00:00:00 2001
From: Robert Kaussow <mail@thegeeklab.de>
Date: Sun, 29 May 2022 22:06:59 +0200
Subject: [PATCH] docs: refactor plugin properties

---
 _docs/{ => content}/_index.md      | 45 ++++++++++++++++--------------
 _docs/data/data.yaml               | 34 ++++++++++++++++++++++
 cmd/drone-github-comment/config.go | 13 +++++----
 3 files changed, 65 insertions(+), 27 deletions(-)
 rename _docs/{ => content}/_index.md (81%)
 create mode 100644 _docs/data/data.yaml

diff --git a/_docs/_index.md b/_docs/content/_index.md
similarity index 81%
rename from _docs/_index.md
rename to _docs/content/_index.md
index 5af30f6..0c898a4 100644
--- a/_docs/_index.md
+++ b/_docs/content/_index.md
@@ -17,6 +17,29 @@ Drone plugin to add comments to GitHub Issues and Pull Requests.
 <!-- spellchecker-enable -->
 <!-- prettier-ignore-end -->
 
+## Usage
+
+```YAML
+kind: pipeline
+name: default
+
+steps:
+  - name: pr-comment
+    image: thegeeklab/drone-github-comment
+    settings:
+      api_key: ghp_3LbMg9Kncpdkhjp3bh3dMnKNXLjVMTsXk4sM
+      message: "CI run completed successfully"
+      update: true
+```
+
+### Parameters
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< propertylist name=drone-s3-sync.data >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
 ## Build
 
 Build the binary with the following command:
@@ -36,7 +59,7 @@ Build the Docker image with the following command:
 docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-github-comment .
 ```
 
-## Usage
+## Test
 
 ```Shell
 docker run --rm \
@@ -50,23 +73,3 @@ docker run --rm \
   -w $(pwd) \
   thegeeklab/drone-github-comment
 ```
-
-### Parameters
-
-api_key
-: sets api key to access github api
-
-base_url
-: sets api url; need to be changed for gh enterprise (default `https://api.github.com`)
-
-key
-: sets unique key to assign to comment
-
-message
-: sets file or string with comment message
-
-update
-: enables update of an existing comment that matches the key
-
-skip_missing
-: skips comment creation if the given message file does not exist (default `false`)
diff --git a/_docs/data/data.yaml b/_docs/data/data.yaml
new file mode 100644
index 0000000..66ac850
--- /dev/null
+++ b/_docs/data/data.yaml
@@ -0,0 +1,34 @@
+---
+properties:
+  api_key:
+    description: Personal Access token to access the GitHub API.
+    type: string
+    required: false
+
+  base_url:
+    description: API URL. Only need to be changed for GitHub enterprise in most cases
+    defaultValue: https://api.github.com
+    type: string
+    required: false
+
+  key:
+    description: Unique identifier to assign to a comment. The identifier is used to update an existing comment.
+    type: string
+    required: false
+
+  message:
+    description: File or string that contains the comment text.
+    type: string
+    required: false
+
+  update:
+    description: Enables update of an existing comment that matches the key.
+    defaultValue: false
+    type: bool
+    required: false
+
+  skip_missing:
+    description: Skips comment creation if the given message file does not exist
+    defaultValue: false
+    type: bool
+    required: false
diff --git a/cmd/drone-github-comment/config.go b/cmd/drone-github-comment/config.go
index 4c4f38c..d316608 100644
--- a/cmd/drone-github-comment/config.go
+++ b/cmd/drone-github-comment/config.go
@@ -11,14 +11,14 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "api-key",
 			EnvVars:     []string{"PLUGIN_API_KEY", "GITHUB_COMMENT_API_KEY"},
-			Usage:       "sets api key to access github api",
+			Usage:       "personal access token access github api",
 			Destination: &settings.APIKey,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "base-url",
 			EnvVars:     []string{"PLUGIN_BASE_URL", "GITHUB_COMMENT_BASE_URL"},
-			Usage:       "sets api url; need to be changed for gh enterprise",
+			Usage:       "api url",
 			Value:       "https://api.github.com/",
 			Destination: &settings.BaseURL,
 			Category:    category,
@@ -26,28 +26,29 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "key",
 			EnvVars:     []string{"PLUGIN_KEY", "GITHUB_COMMENT_KEY"},
-			Usage:       "sets unique key to assign to comment",
+			Usage:       "unique identifier to assign to comment",
 			Destination: &settings.Key,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "message",
 			EnvVars:     []string{"PLUGIN_MESSAGE", "GITHUB_COMMENT_MESSAGE"},
-			Usage:       "sets file or string with comment message",
+			Usage:       "file or string that holds the comment text",
 			Destination: &settings.Message,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "update",
 			EnvVars:     []string{"PLUGIN_UPDATE", "GITHUB_COMMENT_UPDATE"},
-			Usage:       "enables update of an existing comment that matches the key",
+			Usage:       "update existing comment that matches the key",
+			Value:       false,
 			Destination: &settings.Update,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "skip-missing",
 			EnvVars:     []string{"PLUGIN_SKIP_MISSING", "GITHUB_COMMENT_SKIP_MISSING"},
-			Usage:       "skips comment creation if the given message file does not exist",
+			Usage:       "skip creation of comment if message file does not exist",
 			Value:       false,
 			Destination: &settings.SkipMissing,
 			Category:    category,