chore: cleanup docs (#74)

.gitignore

@@ -1,6 +1,7 @@
 /dist
 /release
 /wp-matrix*
+docs/data/data-raw.yaml
 
 coverage.out
 CHANGELOG.md

Makefile

@@ -67,6 +67,10 @@ lint: golangci-lint
 generate:
 	$(GO) generate $(GENERATE)
 
+.PHONY: generate-docs
+generate-docs:
+	$(GO) generate ./cmd/$(EXECUTABLE)/flags.go
+
 .PHONY: test
 test:
 	$(GO) run $(GOTESTSUM_PACKAGE) --no-color=false -- -coverprofile=coverage.out $(PACKAGES)

cmd/wp-matrix/docs.go

@@ -0,0 +1,58 @@
+//go:build generate
+// +build generate
+
+package main
+
+import (
+	"bytes"
+	"embed"
+	"fmt"
+	"os"
+	"text/template"
+
+	"github.com/thegeeklab/wp-matrix/plugin"
+	"github.com/thegeeklab/wp-plugin-go/docs"
+	wp "github.com/thegeeklab/wp-plugin-go/plugin"
+	wp_template "github.com/thegeeklab/wp-plugin-go/template"
+	"github.com/urfave/cli/v2"
+)
+
+//go:embed templates/docs-data.yaml.tmpl
+var yamlTemplate embed.FS
+
+func main() {
+	settings := &plugin.Settings{}
+	app := &cli.App{
+		Flags: settingsFlags(settings, wp.FlagsPluginCategory),
+	}
+
+	out, err := toYAML(app)
+	if err != nil {
+		panic(err)
+	}
+
+	fi, err := os.Create("../../docs/data/data-raw.yaml")
+	if err != nil {
+		panic(err)
+	}
+	defer fi.Close()
+	if _, err := fi.WriteString(out); err != nil {
+		panic(err)
+	}
+}
+
+func toYAML(app *cli.App) (string, error) {
+	var w bytes.Buffer
+
+	yamlTmpl, err := template.New("docs").Funcs(wp_template.LoadFuncMap()).ParseFS(yamlTemplate, "templates/docs-data.yaml.tmpl")
+	if err != nil {
+		fmt.Println(yamlTmpl)
+		return "", err
+	}
+
+	if err := yamlTmpl.ExecuteTemplate(&w, "docs-data.yaml.tmpl", docs.GetTemplateData(app)); err != nil {
+		return "", err
+	}
+
+	return w.String(), nil
+}

cmd/wp-matrix/flags.go

@@ -12,6 +12,8 @@ import (
 )
 
 // settingsFlags has the cli.Flags for the plugin.Settings.
+//
+//go:generate go run docs.go flags.go
 func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 	return []cli.Flag{
 		&cli.StringFlag{
@@ -30,14 +32,14 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		},
 		&cli.StringFlag{
 			Name:        "userid",
-			EnvVars:     []string{"PLUGIN_USERID,PLUGIN_USER_ID", "MATRIX_USERID", "MATRIX_USER_ID"},
-			Usage:       "authentication user id",
+			EnvVars:     []string{"PLUGIN_USER_ID", "PLUGIN_USERID", "MATRIX_USER_ID", "MATRIX_USERID"},
+			Usage:       "authentication user ID",
 			Destination: &settings.UserID,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "accesstoken",
-			EnvVars:     []string{"PLUGIN_ACCESSTOKEN,PLUGIN_ACCESS_TOKEN", "MATRIX_ACCESSTOKEN", "MATRIX_ACCESS_TOKEN"},
+			EnvVars:     []string{"PLUGIN_ACCESS_TOKEN", "PLUGIN_ACCESSTOKEN", "MATRIX_ACCESS_TOKEN", "MATRIX_ACCESSTOKEN"},
 			Usage:       "authentication access token",
 			Destination: &settings.AccessToken,
 			Category:    category,
@@ -60,7 +62,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "template",
 			EnvVars:     []string{"PLUGIN_TEMPLATE", "MATRIX_TEMPLATE"},
-			Usage:       "message template",
+			Usage:       "golang template for the message",
 			Value:       plugin.DefaultMessageTemplate,
 			Destination: &settings.Template,
 			Category:    category,

cmd/wp-matrix/templates/docs-data.yaml.tmpl

@@ -0,0 +1,18 @@
+---
+{{- if .GlobalArgs }}
+properties:
+{{- range $v := .GlobalArgs }}
+  - name: {{ $v.Name }}
+    {{- with $v.Description }}
+    description: |
+      {{ . | ToSentence }}
+    {{- end }}
+    {{- with $v.Type }}
+    type: {{ . }}
+    {{- end }}
+    {{- with $v.Default }}
+    defaultvalue: {{ . }}
+    {{- end }}
+    required: {{ default false $v.Required }}
+{{ end -}}
+{{ end -}}

docs/content/_index.md

@@ -26,7 +26,7 @@ name: default
 
 steps:
 - name: notify
-  image: thegeeklab/matrix
+  image: quay.io/thegeeklab/matrix
   settings:
     homeserver: https://matrix.org
     roomid: abcdefghijklmnopqrstuvwxyz:matrix.org

docs/data/data.yaml

@@ -1,51 +1,67 @@
 ---
 properties:
-  - name: username
-    description: Authentication username. If set, the `password` parameter is required as well.
-    type: string
-    required: false
-
-  - name: password
-    description: Authentication password.
-    type: string
-    required: false
-
-  - name: user_id
-    description: Aauthentication User ID. If set, the `access_token` parameter is required as well.
-    type: string
-    required: false
-
   - name: access_token
-    description: Authentication access token.
+    description: |
+      Authentication access token.
     type: string
     required: false
 
   - name: homeserver
-    description: The Matrix homeserver url to use.
-    defaultValue: https://matrix.org
+    description: |
+      Matrix home server url.
+    type: string
+    defaultvalue: "https://matrix.org"
+    required: false
+
+  - name: password
+    description: |
+      Authentication password.
     type: string
     required: false
 
   - name: roomid
-    description: Room ID to send messages to.
+    description: |
+      Roomid to send messages to.
     type: string
     required: false
 
   - name: template
     description: |
-      Golang template for the message. The [Metadata struct](https://pkg.go.dev/github.com/thegeeklab/wp-plugin-go/plugin#Metadata)
-      is exposed to the template and all fields can be referenced. To extend the functionality, [sprig functions](https://masterminds.github.io/sprig/) can also be used.
-    defaultValue: |
+      Golang template for the message.
+
+      The [Metadata struct](https://pkg.go.dev/github.com/thegeeklab/wp-plugin-go/plugin#Metadata) is exposed
+      to the template and all fields can be referenced. To extend the functionality,
+      [sprig functions](https://masterminds.github.io/sprig/) can also be used.
+    type: string
+    defaultvalue: |
       Status: **{{ .Pipeline.Status }}**
       Build: [{{ .Repository.Slug }}]({{ .Pipeline.URL }}){{ if .Curr.Branch }} ({{ .Curr.Branch }}){{ end }} by {{ .Curr.Author.Name }}
-      Message: {{ .Curr.Message }}{{ if .Curr.URL }} ([source]({{ .Curr.URL }})){{ end }}
-    type: string
+      Message: {{ .Curr.Title }}{{ if .Curr.URL }} ([source]({{ .Curr.URL }})){{ end }}
     required: false
 
   - name: template_unsafe
     description: |
-      By default, raw HTML and potentially dangerous links in the template are not rendered. If you want to use inline HTML, you may need to turn this on.
-      In such cases, please ensure that the CI configuration files in the Git repository are protected against malicious changes.
-    defaultValue: false
+      Render raw HTML and potentially dangerous links in template.
+
+      By default, raw HTML and potentially dangerous links in the template are not rendered. If inline HTML is used,
+      it may be necessary to activate this option. In such cases, please ensure that the CI configuration files
+      in the git repository are protected against malicious changes.
     type: bool
+    defaultvalue: false
+    required: false
+
+  - name: user_id
+    description: |
+      Authentication user ID.
+
+      If set, the `access_token` parameter is required as well.
+    type: string
+    required: false
+
+  - name: username
+    description: |
+      Authentication username.
+
+      If set, the `password` parameter is required as well.
+    type: string
     required: false