diff --git a/.gitignore b/.gitignore index 6ca866f..e9b3212 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /dist /release /wp-matrix* +docs/data/data-raw.yaml coverage.out CHANGELOG.md diff --git a/Makefile b/Makefile index 5a93461..ef611e4 100644 --- a/Makefile +++ b/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) diff --git a/cmd/wp-matrix/docs.go b/cmd/wp-matrix/docs.go new file mode 100644 index 0000000..9b47148 --- /dev/null +++ b/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 +} diff --git a/cmd/wp-matrix/config.go b/cmd/wp-matrix/flags.go similarity index 86% rename from cmd/wp-matrix/config.go rename to cmd/wp-matrix/flags.go index da9574a..d5a7071 100644 --- a/cmd/wp-matrix/config.go +++ b/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, diff --git a/cmd/wp-matrix/templates/docs-data.yaml.tmpl b/cmd/wp-matrix/templates/docs-data.yaml.tmpl new file mode 100644 index 0000000..7342910 --- /dev/null +++ b/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 -}} diff --git a/docs/content/_index.md b/docs/content/_index.md index 026dc07..c74e328 100644 --- a/docs/content/_index.md +++ b/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 diff --git a/docs/data/data.yaml b/docs/data/data.yaml index 4c0671c..bb39a3f 100644 --- a/docs/data/data.yaml +++ b/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