docs: config partial generation

Author: LukasGentele

docs/README.md

@@ -16,30 +16,38 @@ yarn start
 ```
 This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
 
-### Generate Config Reference (devspace.yaml)
-```bash
-cd ../ # main project directory
-
-# JSON Schema:
-go run ./hack/docs/config/reference.go >docs/schemas/config-jsonschema.json
+### Production Build
+```
+yarn build
+```
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-# Open API Spec:
-go run ./hack/docs/config/reference.go true >docs/schemas/config-openapi.json
+### Create New Major Version
+```bash
+yarn run docusaurus docs:version 5.x
 ```
 
 ### Generate CLI Reference
 ```bash
 cd ../ # main project directory
-go run ./hack/gen-docs.go
+go run ./docs/hack/cli/main.go
 ```
 
-### Create Version
+### Generate Partials For Config (devspace.yaml)
 ```bash
-yarn run docusaurus docs:version 5.x
-```
+cd ../ # main project directory
 
-### Build
+go run ./docs/hack/config/partials/main.go
 ```
-yarn build
+
+
+### Generate Schema For Config (devspace.yaml)
+```bash
+cd ../ # main project directory
+
+# JSON Schema:
+go run ./docs/hack/config/schema/main.go >docs/schemas/config-jsonschema.json
+
+# Open API Spec:
+go run ./docs/hack/config/schema/main.go true >docs/schemas/config-openapi.json
 ```
-This command generates static content into the `build` directory and can be served using any static contents hosting service.

hack/docs/cli/reference.go docs/hack/cli/main.gohack/docs/cli/reference.go renamed to docs/hack/cli/main.go

@@ -0,0 +1,144 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/invopop/jsonschema"
+	"github.com/loft-sh/devspace/docs/hack/util"
+	"github.com/loft-sh/devspace/pkg/devspace/config/versions/latest"
+)
+
+const configPartialBasePath = "docs/pages/configuration/_partials/"
+
+func main() {
+	r := new(jsonschema.Reflector)
+	r.AllowAdditionalProperties = true
+	r.PreferYAMLSchema = true
+	r.RequiredFromJSONSchemaTags = false
+	r.YAMLEmbeddedStructs = false
+	r.ExpandedStruct = true
+
+	err := r.AddGoComments("github.com/loft-sh/devspace", "./pkg/devspace/config/versions/latest")
+	if err != nil {
+		panic(err)
+	}
+
+	schema := r.Reflect(&latest.Config{})
+
+	createSections("", schema, schema.Definitions, 1)
+}
+
+func createSections(prefix string, schema *jsonschema.Schema, definitions jsonschema.Definitions, depth int) string {
+	partialImports := &[]string{}
+	content := ""
+
+	for _, fieldName := range schema.Properties.Keys() {
+
+		field, ok := schema.Properties.Get(fieldName)
+		if ok {
+			if fieldSchema, ok := field.(*jsonschema.Schema); ok {
+				fieldContent := ""
+				fieldFile := fmt.Sprintf(configPartialBasePath+"%s/%s%s.mdx", latest.Version, prefix, fieldName)
+
+				ref := ""
+				if fieldSchema.Type == "array" {
+					ref = fieldSchema.Items.Ref
+				} else if patternPropertySchema, ok := fieldSchema.PatternProperties[".*"]; ok {
+					ref = patternPropertySchema.Ref
+				} else if fieldSchema.Ref != "" {
+					ref = fieldSchema.Ref
+				}
+
+				if ref != "" {
+					refSplit := strings.Split(ref, "/")
+					nestedSchema, ok := definitions[refSplit[len(refSplit)-1]]
+
+					if ok {
+						newPrefix := prefix + fieldName + "/"
+						createSections(newPrefix, nestedSchema, definitions, depth+1)
+					}
+				} else {
+					required := ""
+					if contains(schema.Required, fieldName) {
+						required = util.TemplateConfigFieldRequired
+					}
+
+					fieldTypeRaw := fieldSchema.Type
+					if fieldTypeRaw == "array" {
+						fieldTypeRaw = fieldSchema.Items.Type + "[]"
+					}
+					fieldType := fmt.Sprintf(util.TemplateConfigFieldType, fieldTypeRaw)
+					fieldDefault := ""
+					if fieldSchema.Default != nil {
+						fieldDefault = fmt.Sprintf(util.TemplateConfigFieldType, fieldSchema.Default)
+					}
+
+					fieldContent = fmt.Sprintf(util.TemplateConfigField, fieldName, required, fieldType, fieldDefault, fieldSchema.Description)
+
+					err := os.MkdirAll(filepath.Dir(fieldFile), os.ModePerm)
+					if err != nil {
+						panic(err)
+					}
+
+					err = ioutil.WriteFile(fieldFile, []byte(fieldContent), os.ModePerm)
+					if err != nil {
+						panic(err)
+					}
+				}
+
+				*partialImports = append(*partialImports, fieldFile)
+				fieldPartial := fmt.Sprintf(util.TemplatePartialUse, util.GetPartialImportName(fieldFile))
+				if ref != "" {
+					fieldSummary := fmt.Sprintf("<h%d><code>%s</code></h%d>", depth+1, fieldName, depth+1)
+					fieldPartial = fmt.Sprintf("<details><summary>%s</summary>\n%s\n</details>", fieldSummary, fieldPartial)
+				}
+
+				content = content + "\n\n" + fieldPartial
+			}
+		}
+	}
+
+	if prefix == "" {
+		prefix = "reference"
+	}
+
+	pageFile := fmt.Sprintf(configPartialBasePath+"%s/%s.mdx", latest.Version, strings.TrimSuffix(prefix, "/"))
+
+	importContent := ""
+	for _, partialImport := range *partialImports {
+		partialImportPath, err := filepath.Rel(filepath.Dir(pageFile), partialImport)
+		if err != nil {
+			panic(err)
+		}
+
+		if partialImportPath[0:1] != "." {
+			partialImportPath = "./" + partialImportPath
+		}
+
+		importContent = importContent + fmt.Sprintf(util.TemplatePartialImport, util.GetPartialImportName(partialImport), partialImportPath)
+	}
+
+	content = fmt.Sprintf("%s%s", importContent, content)
+
+	err := ioutil.WriteFile(pageFile, []byte(content), os.ModePerm)
+	if err != nil {
+		panic(err)
+	}
+
+	//fmt.Println(content)
+
+	return content
+}
+
+func contains(s []string, e string) bool {
+	for _, a := range s {
+		if a == e {
+			return true
+		}
+	}
+	return false
+}

docs/hack/config/partials/main.go

@@ -0,0 +1,130 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+	"reflect"
+
+	"github.com/loft-sh/devspace/docs/hack/util"
+	"github.com/loft-sh/devspace/pkg/devspace/pipeline/engine/pipelinehandler/commands"
+)
+
+type Function struct {
+	Handler interface{}
+	Flags   interface{}
+}
+
+func main() {
+	for functionName := range Functions {
+		function := Functions[functionName]
+
+		pageFile := fmt.Sprintf(util.PagePathFunction, functionName)
+		pageContent := []byte{}
+
+		_, err := os.Stat(pageFile)
+		if err == nil {
+			pageContent, err = ioutil.ReadFile(pageFile)
+			if err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		functionDescription := util.GetExistingDescription(string(pageContent))
+
+		partialImports := &[]string{}
+
+		argsContent := fmt.Sprintf("The function `%s` does not expect any arguments.", functionName)
+
+		funcHandlerRef := reflect.ValueOf(function.Handler).Type()
+		maxArguments := funcHandlerRef.NumIn()
+		if maxArguments > 0 {
+			lastArgument := funcHandlerRef.In(maxArguments - 1)
+			if lastArgument.String() == "[]string" {
+				argsContent = fmt.Sprintf("The function `%s` expects arguments.", functionName)
+
+				existingArgsContent := util.GetSection("Arguments", string(pageContent))
+				if existingArgsContent != "" {
+					argsContent = existingArgsContent
+				}
+			}
+		}
+
+		flagRef := reflect.ValueOf(function.Flags).Type()
+		flagContent := getFlagReference(functionName, flagRef, partialImports, string(pageContent))
+		if flagContent == "" {
+			continue
+		}
+
+		importContent := ""
+		for _, partialImport := range *partialImports {
+			partialImportPath, err := filepath.Rel(filepath.Dir(pageFile), partialImport)
+			if err != nil {
+				panic(err)
+			}
+
+			if partialImportPath[0:1] != "." {
+				partialImportPath = "./" + partialImportPath
+			}
+
+			importContent = importContent + fmt.Sprintf(util.TemplatePartialImport, util.GetPartialImportName(partialImport), partialImportPath)
+		}
+
+		content := fmt.Sprintf(util.TemplatePage, functionName, functionName, importContent, functionDescription, argsContent, flagContent)
+
+		err = ioutil.WriteFile(pageFile, []byte(content), 0)
+		if err != nil {
+			panic(err)
+		}
+	}
+}
+
+func getFlagReference(functionName string, flagRef reflect.Type, partialImports *[]string, pageContent string) string {
+	content := ""
+
+	for i := 0; i < flagRef.NumField(); i++ {
+		field := flagRef.Field(i)
+		if field.Anonymous {
+			content = content + getFlagReference(functionName, field.Type, partialImports, pageContent)
+			continue
+		}
+
+		long := field.Tag.Get("long")
+		if long == "" {
+			continue
+		}
+
+		existingFlagContent := util.GetPartOfAutogenSection("`--"+long, pageContent)
+
+		short := flagRef.Field(i).Tag.Get("short")
+		description := flagRef.Field(i).Tag.Get("description")
+
+		if short != "" {
+			short = " / -" + short
+		}
+
+		flagPartial := fmt.Sprintf(util.PartialPathFlag, functionName, long)
+		_, err := os.Stat(flagPartial)
+		if err == nil {
+			*partialImports = append(*partialImports, flagPartial)
+			description = description + "\n\n" + fmt.Sprintf(util.TemplatePartialUseFlag, util.GetPartialImportName(flagPartial), functionName, long)
+		}
+
+		content = content + fmt.Sprintf(util.TemplateFlag, long, short, description) + existingFlagContent
+	}
+
+	return content
+}
+
+var Functions = map[string]Function{
+	"build_images": {
+		Handler: commands.BuildImages,
+		Flags:   commands.BuildImagesOptions{},
+	},
+	"create_deployments": {
+		Handler: commands.CreateDeployments,
+		Flags:   commands.CreateDeploymentsOptions{},
+	},
+}

hack/docs/config/reference.go docs/hack/config/schema/main.gohack/docs/config/reference.go renamed to docs/hack/config/schema/main.go

@@ -0,0 +1,34 @@
+package util
+
+import (
+	"regexp"
+)
+
+func GetExistingDescription(pageContent string) string {
+	match := regexp.MustCompile(`(?is)^---.*?---\s*(import.*?\n)*\s*(.*?)\s*\n###? .*$`).ReplaceAllString(pageContent, "$2")
+
+	if match != pageContent && match != "" {
+		return "\n" + match + "\n"
+	}
+	return ""
+}
+
+func GetSection(headlineText, pageContent string) string {
+	regex := `(?is)^.*\s*\n###?\s+` + headlineText + `\s*(.*?)(\n+((##)|$).*)?$`
+	match := regexp.MustCompile(regex).ReplaceAllString(pageContent, "$1")
+
+	if match != pageContent && match != "" {
+		return match
+	}
+	return ""
+}
+
+func GetPartOfAutogenSection(headlineText, pageContent string) string {
+	regex := "(?is)^.*" + AutoGenTagBegin + `\s*\n###?\s+` + headlineText + `.*?` + AutoGenTagEnd + `\s*(.*?)\s*` + AutoGenTagBegin + ".*$"
+	match := regexp.MustCompile(regex).ReplaceAllString(pageContent, "$1")
+
+	if match != pageContent && match != "" {
+		return match + "\n\n"
+	}
+	return ""
+}

docs/hack/functions/main.go

@@ -0,0 +1,17 @@
+package util
+
+import (
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+var partialNameRegex = regexp.MustCompile(`(\..*$)|[^a-zA-Z-]`)
+
+func GetPartialImportName(partialImport string) string {
+	basename := filepath.Base(partialImport)
+	basename = partialNameRegex.ReplaceAllString(basename, "")
+
+	return fmt.Sprintf("Partial%s", strings.Title(basename))
+}