docs: generate attributes from source

Author: jippi

.github/workflows/docs.yml

@@ -21,5 +21,12 @@ jobs:
           version: 3.x
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
       - name: setup
+        run: task setup
+
+      - name: deploy
         run: task docs:deploy

.gitignore

@@ -16,3 +16,4 @@
 /schema/ignore
 /scm-engine
 /scm-engine.exe
+/docs/gitlab/script-attributes.md

docs/gitlab/script-attributes.md

@@ -1,9 +1,55 @@
-{{- define "attributes" -}}
-{{- range .Attributes -}}
-{{ if .IsCustomType -}}{{- template "attributes" . }}{{- else }}
-- `{{ .BlockName }}` ({{ if .Optional }}optional {{ end }}{{ .Type }}) {{ .Description }}{{- end -}}
-{{- end }}
+{{- define "enum_attribute" -}}
+- `{{ .BlockName }}` ({{ if .Optional }}optional {{ end }}enum) {{ .Description }}
+  {{- range .Enum.Values }}
+      - `{{ .Name }}` - {{ .Description }}
+  {{- end -}}
 {{- end -}}
 
-### Attributes
-{{ template "attributes" . -}}
+{{- define "single_attribute" -}}- `{{ .BlockName }}` ({{ if .Optional }}optional {{ end }}{{ .Type }}){{ if .Description}} {{ .Description -}}{{ end }}{{- end -}}
+
+{{- define "description" }}{{ if .Description }}
+{{ .Description }}
+{{ end -}}
+{{ end -}}
+
+{{- define "headline" }}
+{{ .GetHeadline }}
+{{ end -}}
+
+{{- define "custom_type" }}{{ template "headline" . }}{{ template "description" . }}
+{{ template "attributes" . }}{{ end -}}
+
+{{- define "attributes" -}}{{- range .Attributes -}}
+{{- if .IsCustomType }}{{ template "custom_type" . }}
+{{- else if .IsEnum }}{{- template "enum_attribute" . }}
+{{- else }}{{- template "single_attribute" . }}
+{{ end }}
+{{- end -}}
+{{- end -}}
+
+# Script Attributes
+
+!!! tip "The [Expr Language Definition](https://expr-lang.org/docs/language-definition) is a great resource to learn more about the language"
+
+!!! note
+
+    Missing an attribute? The `schema/gitlab.schema.graphqls` file are what is used to query GitLab, adding the missing `field` to the right `type` should make it accessible. Please open an issue or Pull Request if something is missing.
+
+The following attributes are available in `script` fields.
+
+They can be accessed exactly as shown in this list.
+
+{{ template "attributes" . }}
+
+## `webhook_event`
+
+!!! tip "`webhook_event` attribute is only available in `server` mode"
+
+    You have access to the raw webhook event payload via `webhook_event.*` attributes (not listed below) in Expr script fields when using [`server`](#server) mode.
+
+    See the [GitLab Webhook Events documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html) for available fields.
+
+    The attributes are named _exactly_ as documented in the GitLab documentation.
+
+- [`Comments`](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#comment-events) - A comment is made or edited on an issue or merge request.
+- [`Merge request events`](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events) - A merge request is created, updated, or merged.

schema/docs.tmpl

@@ -7,12 +7,12 @@ import (
 	"cmp"
 	_ "embed"
 	"fmt"
-	"html/template"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"slices"
 	"strings"
+	"text/template"
 
 	"github.com/99designs/gqlgen/api"
 	"github.com/99designs/gqlgen/codegen/config"
@@ -61,6 +61,10 @@ func main() {
 		panic(err)
 	}
 
+	if err := os.WriteFile(getRootPath()+"/docs/gitlab/script-attributes.md", []byte(index.String()), 0600); err != nil {
+		panic(err)
+	}
+
 	fmt.Println(index.String())
 }
 
@@ -79,12 +83,16 @@ func nest(props []*Property) {
 					Optional:     nested.Optional,
 					Type:         nested.Type,
 					IsSlice:      nested.IsSlice,
+					IsEnum:       nested.IsEnum,
+					Enum:         nested.Enum,
 					IsCustomType: nested.IsCustomType,
 				})
 			}
 		}
 
 		nest(field.Attributes)
+
+		slices.SortFunc(field.Attributes, sortSlice)
 	}
 }
 
@@ -139,6 +147,12 @@ func fieldHook(td *ast.Definition, fd *ast.FieldDefinition, f *modelgen.Field) (
 }
 
 func mutateHook(b *modelgen.ModelBuild) *modelgen.ModelBuild {
+	enums := map[string]*modelgen.Enum{}
+
+	for _, enum := range b.Enums {
+		enums[enum.Name] = enum
+	}
+
 	for _, model := range b.Models {
 		modelName := model.Name
 
@@ -162,6 +176,11 @@ func mutateHook(b *modelgen.ModelBuild) *modelgen.ModelBuild {
 				return b
 			}
 
+			// We manually document this one in the template!
+			if field.Name == "WebhookEvent" {
+				continue
+			}
+
 			if !strings.Contains(field.Tag, "expr:") {
 				tags.Set(&structtag.Tag{Key: "expr", Name: strcase.ToSnake(field.Name)})
 			}
@@ -189,9 +208,15 @@ func mutateHook(b *modelgen.ModelBuild) *modelgen.ModelBuild {
 					fieldType = filepath.Base(fieldType)
 					fieldType = strings.Split(fieldType, ".")[1]
 					fieldType = strings.TrimPrefix(fieldType, "Context")
-					fieldType = strcase.ToSnake(fieldType)
 
-					fieldProperty.IsCustomType = true
+					// Check if our field is an enum
+					if enum, ok := enums[fieldType]; ok {
+						fieldProperty.IsEnum = true
+						fieldProperty.Enum = enum
+					}
+					fieldProperty.IsCustomType = !fieldProperty.IsEnum
+
+					fieldType = strcase.ToSnake(fieldType)
 				}
 
 				switch {
@@ -207,8 +232,6 @@ func mutateHook(b *modelgen.ModelBuild) *modelgen.ModelBuild {
 				modelProperty.AddAttribute(fieldProperty)
 			} // end expr tag is set
 
-			slices.SortFunc(modelProperty.Attributes, sortSlice)
-
 			field.Tag = tags.String()
 		} // end fields loop
 
@@ -240,6 +263,9 @@ type Property struct {
 	// Used to show "String list" or "Block list" in the documentation output
 	IsSlice bool
 
+	IsEnum bool
+	Enum   *modelgen.Enum
+
 	IsCustomType bool
 
 	// Contains any sub-attributes for this Property.
@@ -262,6 +288,10 @@ func (p *Property) AddAttribute(attrs ...*Property) {
 	}
 }
 
+func (p Property) GetHeadline() string {
+	return fmt.Sprintf("%s `%s` {#%s data-toc-label=%q}", strings.Repeat("#", len(p.getHierarchy())+1), p.BlockName(), p.Name, p.Name)
+}
+
 // getHierarchy returns a slice representing all ancestors of this Property
 // and its own Property name
 func (p Property) getHierarchy() []string {
@@ -293,5 +323,18 @@ func (p *Property) BlockName() string {
 }
 
 func sortSlice(i, j *Property) int {
+	// non-custom types first
+	if i.IsCustomType && j.IsCustomType {
+		return 0
+	}
+
+	if i.IsCustomType && !j.IsCustomType {
+		return 1
+	}
+
+	if !i.IsCustomType && j.IsCustomType {
+		return -1
+	}
+
 	return cmp.Compare(i.Name, j.Name)
 }