docs: show enums in reference and allow groupings

Author: LukasGentele

docs/hack/config/partials/main.go

@@ -5,21 +5,30 @@ import (
 	"io/ioutil"
 	"os"
 	"path/filepath"
+	"sort"
+	"strconv"
 	"strings"
 
+	"github.com/gertd/go-pluralize"
 	"github.com/invopop/jsonschema"
 	"github.com/loft-sh/devspace/docs/hack/util"
+	"github.com/loft-sh/devspace/pkg/devspace/config/versions"
 	"github.com/loft-sh/devspace/pkg/devspace/config/versions/latest"
 )
 
 const configPartialBasePath = "docs/pages/configuration/_partials/"
 const nameFieldName = "name"
+const versionFieldName = "version"
+const groupKey = "group"
+const groupNameKey = "group_name"
+
+var pluralizeClient = pluralize.NewClient()
 
 func main() {
 	r := new(jsonschema.Reflector)
 	r.AllowAdditionalProperties = true
 	r.PreferYAMLSchema = true
-	r.RequiredFromJSONSchemaTags = false
+	r.RequiredFromJSONSchemaTags = true
 	r.YAMLEmbeddedStructs = false
 	r.ExpandedStruct = true
 
@@ -30,14 +39,51 @@ func main() {
 
 	schema := r.Reflect(&latest.Config{})
 
+	versionField, ok := schema.Properties.Get(versionFieldName)
+	if ok {
+		if fieldSchema, ok := versionField.(*jsonschema.Schema); ok {
+			versionEnum := []string{}
+			for version := range versions.VersionLoader {
+				versionEnum = append(versionEnum, version)
+			}
+
+			sort.SliceStable(versionEnum, func(a, b int) bool {
+				majorA, _ := strconv.Atoi(string(versionEnum[a][1]))
+				majorB, _ := strconv.Atoi(string(versionEnum[b][1]))
+				minorA, _ := strconv.Atoi(string(versionEnum[a][6:]))
+				minorB, _ := strconv.Atoi(string(versionEnum[b][6:]))
+
+				if majorA == majorB {
+					return minorA > minorB
+				} else {
+					return majorA > majorB
+				}
+			})
+
+			fieldSchema.Enum = []interface{}{}
+			for _, version := range versionEnum {
+				fieldSchema.Enum = append(fieldSchema.Enum, version)
+			}
+		}
+	}
+
 	createSections("", schema, schema.Definitions, 1, false)
 }
 
+type Group struct {
+	File    string
+	Name    string
+	Content string
+	Imports *[]string
+}
+
 func createSections(prefix string, schema *jsonschema.Schema, definitions jsonschema.Definitions, depth int, parentIsNameObjectMap bool) string {
 	partialImports := &[]string{}
 	content := ""
 	headlinePrefix := strings.Repeat("#", depth+1) + " "
 
+	groups := map[string]*Group{}
+
 	for _, fieldName := range schema.Properties.Keys() {
 		if parentIsNameObjectMap && fieldName == nameFieldName {
 			continue
@@ -50,14 +96,16 @@ func createSections(prefix string, schema *jsonschema.Schema, definitions jsonsc
 				fieldFile := fmt.Sprintf(configPartialBasePath+"%s/%s%s.mdx", latest.Version, prefix, fieldName)
 				fieldType := "object"
 				isNameObjectMap := false
+				groupID, _ := fieldSchema.Extras[groupKey].(string)
 
+				var patternPropertySchema *jsonschema.Schema
 				var nestedSchema *jsonschema.Schema
 
 				ref := ""
 				if fieldSchema.Type == "array" {
 					ref = fieldSchema.Items.Ref
 					fieldType = "object[]"
-				} else if patternPropertySchema, ok := fieldSchema.PatternProperties[".*"]; ok {
+				} else if patternPropertySchema, ok = fieldSchema.PatternProperties[".*"]; ok {
 					ref = patternPropertySchema.Ref
 					isNameObjectMap = true
 				} else if fieldSchema.Ref != "" {
@@ -74,17 +122,49 @@ func createSections(prefix string, schema *jsonschema.Schema, definitions jsonsc
 					}
 				} else {
 					required := contains(schema.Required, fieldName)
+					fieldDefault := ""
+
 					fieldType = fieldSchema.Type
+					if fieldType == "" && fieldSchema.OneOf != nil {
+						for _, oneOfType := range fieldSchema.OneOf {
+							if fieldType != "" {
+								fieldType = fieldType + "|"
+							}
+							fieldType = fieldType + oneOfType.Type
+						}
+					}
+
+					if isNameObjectMap {
+						fieldNameSingular := pluralizeClient.Singular(fieldName)
+						fieldType = "<" + fieldNameSingular + "_name>:"
+
+						if patternPropertySchema != nil && patternPropertySchema.Type != "" {
+							fieldType = fieldType + patternPropertySchema.Type
+						} else {
+							fieldType = fieldType + "object"
+						}
+					}
+
 					if fieldType == "array" {
 						fieldType = fieldSchema.Items.Type + "[]"
 					}
 
-					fieldDefault, ok := fieldSchema.Default.(string)
-					if !ok {
-						fieldDefault = ""
+					if fieldType == "boolean" {
+						fieldDefault = "false"
+						if required {
+							fieldDefault = "true"
+							required = false
+						}
+					} else {
+						fieldDefault, ok = fieldSchema.Default.(string)
+						if !ok {
+							fieldDefault = ""
+						}
 					}
 
-					fieldContent = fmt.Sprintf(util.TemplateConfigField, false, " open", headlinePrefix, fieldName, required, fieldType, fieldDefault, fieldSchema.Description, "")
+					enumValues := GetEumValues(fieldSchema, required, &fieldDefault)
+
+					fieldContent = fmt.Sprintf(util.TemplateConfigField, false, " open", headlinePrefix, fieldName, required, fieldType, fieldDefault, enumValues, fieldSchema.Description, "")
 
 					err := os.MkdirAll(filepath.Dir(fieldFile), os.ModePerm)
 					if err != nil {
@@ -97,43 +177,93 @@ func createSections(prefix string, schema *jsonschema.Schema, definitions jsonsc
 					}
 				}
 
-				*partialImports = append(*partialImports, fieldFile)
 				fieldPartial := fmt.Sprintf(util.TemplatePartialUse, util.GetPartialImportName(fieldFile))
 				if ref != "" {
 					if isNameObjectMap && nestedSchema != nil {
 						nameField, ok := nestedSchema.Properties.Get(nameFieldName)
 						if ok {
 							if nameFieldSchema, ok := nameField.(*jsonschema.Schema); ok {
-								fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "open", headlinePrefix, "<"+nameFieldName+">", false, "object", "", nameFieldSchema.Description, fieldPartial)
+								fieldNameSingular := pluralizeClient.Singular(fieldName)
+								nameFieldRequired := true
+								nameFieldDefault := ""
+								nameFieldEnumValues := GetEumValues(nameFieldSchema, nameFieldRequired, &nameFieldDefault)
+
+								fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "open", headlinePrefix, "<"+fieldNameSingular+"_"+nameFieldName+">", nameFieldRequired, "string", nameFieldDefault, nameFieldEnumValues, nameFieldSchema.Description, fieldPartial)
+								fieldType = "&lt;" + fieldNameSingular + "_name&gt;:object"
 							}
 						}
 					}
-					fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "", headlinePrefix, fieldName, false, fieldType, "", fieldSchema.Description, fieldPartial)
+
+					fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "", headlinePrefix, fieldName, false, fieldType, "", "", fieldSchema.Description, fieldPartial)
 				}
 
-				content = content + "\n\n" + fieldPartial
+				if groupID != "" {
+					group, ok := groups[groupID]
+					if !ok {
+						group = &Group{
+							File:    fmt.Sprintf(configPartialBasePath+"%s/%sgroup_%s.mdx", latest.Version, prefix, groupID),
+							Imports: &[]string{},
+						}
+						groups[groupID] = group
+
+						groupPartial := fmt.Sprintf(util.TemplatePartialUse, util.GetPartialImportName(group.File))
+
+						content = content + "\n\n" + groupPartial
+						*partialImports = append(*partialImports, group.File)
+					}
+
+					if groupName, ok := fieldSchema.Extras[groupNameKey]; ok {
+						group.Name = groupName.(string)
+					}
+
+					group.Content = group.Content + fieldPartial
+					*group.Imports = append(*group.Imports, fieldFile)
+				} else {
+					content = content + "\n\n" + fieldPartial
+					*partialImports = append(*partialImports, fieldFile)
+				}
 			}
 		}
 	}
 
-	if prefix == "" {
-		prefix = "reference"
-	}
+	for groupID, group := range groups {
+		groupContent := group.Content
 
-	pageFile := fmt.Sprintf(configPartialBasePath+"%s/%s.mdx", latest.Version, strings.TrimSuffix(prefix, "/"))
+		if group.Name != "" {
+			groupContent = "\n" + `<div className="group-name">` + group.Name + `</div>` + "\n\n" + groupContent
+		}
 
-	importContent := ""
-	for _, partialImport := range *partialImports {
-		partialImportPath, err := filepath.Rel(filepath.Dir(pageFile), partialImport)
+		groupImportContent := ""
+		for _, partialFile := range *group.Imports {
+			groupImportContent = groupImportContent + GetPartialImport(partialFile, group.File)
+		}
+
+		if groupImportContent != "" {
+			groupImportContent = groupImportContent + "\n\n"
+		}
+
+		groupFileContent := fmt.Sprintf(`%s<div className="group" data-group="%s">%s`+"\n"+`</div>`, groupImportContent, groupID, groupContent)
+
+		err := os.MkdirAll(filepath.Dir(group.File), os.ModePerm)
 		if err != nil {
 			panic(err)
 		}
 
-		if partialImportPath[0:1] != "." {
-			partialImportPath = "./" + partialImportPath
+		err = ioutil.WriteFile(group.File, []byte(groupFileContent), os.ModePerm)
+		if err != nil {
+			panic(err)
 		}
+	}
+
+	if prefix == "" {
+		prefix = "reference"
+	}
 
-		importContent = importContent + fmt.Sprintf(util.TemplatePartialImport, util.GetPartialImportName(partialImport), partialImportPath)
+	pageFile := fmt.Sprintf(configPartialBasePath+"%s/%s.mdx", latest.Version, strings.TrimSuffix(prefix, "/"))
+
+	importContent := ""
+	for _, partialFile := range *partialImports {
+		importContent = importContent + GetPartialImport(partialFile, pageFile)
 	}
 
 	content = fmt.Sprintf("%s%s", importContent, content)
@@ -148,6 +278,40 @@ func createSections(prefix string, schema *jsonschema.Schema, definitions jsonsc
 	return content
 }
 
+func GetPartialImport(partialFile, importingFile string) string {
+	partialImportPath, err := filepath.Rel(filepath.Dir(importingFile), partialFile)
+	if err != nil {
+		panic(err)
+	}
+
+	if partialImportPath[0:1] != "." {
+		partialImportPath = "./" + partialImportPath
+	}
+
+	return fmt.Sprintf(util.TemplatePartialImport, util.GetPartialImportName(partialFile), partialImportPath)
+}
+
+func GetEumValues(fieldSchema *jsonschema.Schema, required bool, fieldDefault *string) string {
+	enumValues := ""
+	if fieldSchema.Enum != nil {
+		for i, enumVal := range fieldSchema.Enum {
+			enumValString, ok := enumVal.(string)
+			if ok {
+				if i == 0 && !required && *fieldDefault == "" {
+					*fieldDefault = enumValString
+				}
+
+				if enumValues != "" {
+					enumValues = enumValues + "<br/>"
+				}
+				enumValues = enumValues + enumValString
+			}
+		}
+		enumValues = fmt.Sprintf("<span>%s</span>", enumValues)
+	}
+	return enumValues
+}
+
 func contains(s []string, e string) bool {
 	for _, a := range s {
 		if a == e {

docs/hack/util/templates.go

@@ -39,7 +39,7 @@ const TemplateConfigField = `
 <details className="config-field" data-expandable="%t"%s>
 <summary>
 
-%s` + "`%s`" + ` <span class="config-field-required" data-required="%t">required</span> <span class="config-field-type">%s</span> <span class="config-field-default">%s</span>
+%s` + "`%s`" + ` <span class="config-field-required" data-required="%t">required</span> <span class="config-field-type">%s</span> <span class="config-field-default">%s</span> <span class="config-field-enum">%s</span>
 
 %s
 

docs/pages/configuration/_partials/v2beta1/commands.mdx

@@ -1,28 +1,24 @@
 
 import PartialCommand from "./commands/command.mdx"
-import PartialAfter from "./commands/after.mdx"
-import PartialDisableReplace from "./commands/disableReplace.mdx"
-import PartialInternal from "./commands/internal.mdx"
 import PartialArgs from "./commands/args.mdx"
 import PartialAppendArgs from "./commands/appendArgs.mdx"
 import PartialDescription from "./commands/description.mdx"
+import PartialInternal from "./commands/internal.mdx"
+import PartialAfter from "./commands/after.mdx"
 
 <PartialCommand />
 
 
-<PartialAfter />
-
-
-<PartialDisableReplace />
+<PartialArgs />
 
 
-<PartialInternal />
+<PartialAppendArgs />
 
 
-<PartialArgs />
+<PartialDescription />
 
 
-<PartialAppendArgs />
+<PartialInternal />
 
 
-<PartialDescription />
+<PartialAfter />

docs/pages/configuration/_partials/v2beta1/commands/after.mdx

@@ -2,7 +2,7 @@
 <details className="config-field" data-expandable="false" open>
 <summary>
 
-### `after` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
+### `after` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span> <span class="config-field-enum"></span>
 
 After is executed after the command was run. It is executed also when
 the command was interrupted which will set the env variable COMMAND_INTERRUPT

docs/pages/configuration/_partials/v2beta1/commands/appendArgs.mdx

@@ -2,7 +2,7 @@
 <details className="config-field" data-expandable="false" open>
 <summary>
 
-### `appendArgs` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">boolean</span> <span class="config-field-default"></span>
+### `appendArgs` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">boolean</span> <span class="config-field-default">false</span> <span class="config-field-enum"></span>
 
 AppendArgs will append arguments passed to the DevSpace command automatically to
 the specified command.

docs/pages/configuration/_partials/v2beta1/commands/args.mdx

@@ -2,7 +2,7 @@
 <details className="config-field" data-expandable="false" open>
 <summary>
 
-### `args` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string[]</span> <span class="config-field-default"></span>
+### `args` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string[]</span> <span class="config-field-default"></span> <span class="config-field-enum"></span>
 
 Args are optional and if defined, command is not executed within a shell
 and rather directly.

docs/pages/configuration/_partials/v2beta1/commands/command.mdx

@@ -2,7 +2,7 @@
 <details className="config-field" data-expandable="false" open>
 <summary>
 
-### `command` <span class="config-field-required" data-required="true">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
+### `command` <span class="config-field-required" data-required="true">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span> <span class="config-field-enum"></span>
 
 Command is the command that should be executed. For example: 'echo 123'
 

docs/pages/configuration/_partials/v2beta1/commands/description.mdx

@@ -2,7 +2,7 @@
 <details className="config-field" data-expandable="false" open>
 <summary>
 
-### `description` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
+### `description` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span> <span class="config-field-enum"></span>
 
 Description describes what the command is doing and can be seen in `devspace list commands`