docs(template): add autogenerated docs for options (#98)

Signed-off-by: Tobias Brumhard <[email protected]>

.githooks/pre-commit

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+## compare amount of changed file before and after generate
+CHANGE_STATS=$(git diff --shortstat)
+
+make generate &>/dev/null
+
+CHANGE_STATS_NEW=$(git diff --shortstat)
+
+## we can check to see if this is empty
+if [[ "$CHANGE_STATS" != "$CHANGE_STATS_NEW" ]]; then
+    echo -e "Files have been generated. Pls treat them also."
+    exit 1
+fi
+
+echo "No changes happened due to make generate, ready to proceed"

.golangci.yml

@@ -129,7 +129,9 @@ issues:
         - goerr113
         - funlen
         - goconst
-    - path: dotembed/main\.go
+    # only small tools that use globals for templating
+    # and errors for CLI error output
+    - path: (dotembed|options2md)\/main\.go
       linters:
         - gochecknoglobals
         - goerr113

Makefile

@@ -32,7 +32,8 @@ run: fmt ## Run a controller from your host
 	@go run ./main.go
 
 generate: ## Generates files
-	@go generate ./...
+	@go run cmd/dotembed/main.go -target _template -o embed_gen.go -pkg gotemplate -var FS
+	@go run cmd/options2md/main.go -o docs/options.md
 
 GOLANGCI_LINT = bin/golangci-lint-$(GOLANGCI_VERSION)
 $(GOLANGCI_LINT):

README.md

@@ -71,7 +71,7 @@ make all
 
 ## Options
 
-To get an overview of all options that can be set for the template you can take a look at the [options definition file](pkg/gotemplate/options.go), run the CLI or check out the [testing example values file](pkg/gotemplate/testdata/values.yml).
+To get an overview of all options that can be set for the template you can take a look at the [options docs](docs/options.md), run the CLI or check out the [testing example values file](pkg/gotemplate/testdata/values.yml).
 
 ## Maintainers
 

cmd/dotembed/main.go

@@ -89,18 +89,18 @@ func sortStrings(slice []string) []string {
 }
 
 var (
-	tmplString = `package {{ .Package }}
+	tmplString = `// Code generated by dotembed. DO NOT EDIT.
+package {{ .Package }}
 
 import "embed"
 
 //go:embed {{ join (sort (.EmbedPaths | keys)) " " }}
 var {{ .VariableName }} embed.FS
 `
-	tmpl = template.Must(
-		template.New("").Funcs(template.FuncMap{
-			"join": strings.Join,
-			"keys": keys,
-			"sort": sortStrings,
-		}).Parse(tmplString),
-	)
+	funcMap = template.FuncMap{
+		"join": strings.Join,
+		"keys": keys,
+		"sort": sortStrings,
+	}
+	tmpl = template.Must(template.New("").Funcs(funcMap).Parse(tmplString))
 )

cmd/options2md/main.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+
+	"text/template"
+
+	"github.com/schwarzit/go-template/pkg/gotemplate"
+)
+
+// options2md tranlates all options available in go/template to a markdown file
+// defined by the -o flag. This can be used for documentation.
+func main() {
+	if err := run(os.Args[1:]); err != nil {
+		fmt.Fprintf(os.Stderr, "an error occurred: %s\n", err)
+		os.Exit(1)
+	}
+}
+
+func run(args []string) error {
+	var outputFile string
+	flag.StringVar(&outputFile, "o", "./options.md", "The file to write")
+	flag.CommandLine.Parse(args)
+
+	if outputFile == "" {
+		return errors.New("`o` is a required parameter")
+	}
+
+	file, err := os.Create(outputFile)
+	if err != nil {
+		return err
+	}
+
+	return tmpl.Execute(file, gotemplate.NewOptions(nil))
+}
+
+var (
+	tmplString = `<!-- Code generated by options2md. DO NOT EDIT. -->
+# Options
+
+The following sections describe all options that are currently available for go/template for templating.
+The options are divided into base options and extension options.
+Base options are needed for the minimal base template and are mandatory in any case.
+The extension options on the other hand enable optional features in the template such as gRPC support or open source lincenses.
+
+## Base
+
+| Name | Description |
+| :--- | :---------- |
+{{- range $index, $option := .Base}}
+| {{ $option.Name | code }} | {{ $option.Description | replace "\n" "<br>" }} |
+{{- end}}
+
+## Extensions
+{{- range $index, $category := .Extensions}}
+
+### {{ $category.Name | code }}
+
+| Name | Description |
+| :--- | :---------- |
+{{- range $index, $option := $category.Options}}
+| {{ $option.Name | code }} | {{ $option.Description | replace "\n" "<br>" }} |
+{{- end}}
+{{- end}}
+`
+	funcMap = template.FuncMap{
+		"replace": func(old, new, src string) string {
+			return strings.ReplaceAll(src, old, new)
+		},
+		"code": func(s string) string {
+			return fmt.Sprintf("`%s`", s)
+		},
+	}
+	tmpl = template.Must(template.New("").Funcs(funcMap).Parse(tmplString))
+)

docs/options.md

@@ -0,0 +1,41 @@
+<!-- Code generated by options2md. DO NOT EDIT. -->
+# Options
+
+The following sections describe all options that are currently available for go/template for templating.
+The options are divided into base options and extension options.
+Base options are needed for the minimal base template and are mandatory in any case.
+The extension options on the other hand enable optional features in the template such as gRPC support or open source lincenses.
+
+## Base
+
+| Name | Description |
+| :--- | :---------- |
+| `projectName` | Name of the project |
+| `projectSlug` | Technical name of the project for folders and names. This will also be used as output directory. |
+| `projectDescription` | Description of the project used in the README. |
+| `appName` | The name of the binary that you want to create.<br>Could be the same as your "projectSlug" but since Go supports multiple apps in one repo it could also be sth. else.<br>For example if your project is for some API there could be one app for the server and one CLI client. |
+| `moduleName` | The name of the Go module defined in the "go.mod" file.<br>This is used if you want to "go get" the module.<br>Please be aware that this depends on your version control system.<br>The default points to "github.com" but for devops for example it would look sth. like this "dev.azure.com/org/project/repo.git" |
+| `golangciVersion` | Golangci-lint version to use. |
+
+## Extensions
+
+### `openSource`
+
+| Name | Description |
+| :--- | :---------- |
+| `license` | Set an OpenSource license.<br>Unsure which to pick? Checkout Github's https://choosealicense.com/<br>Options:<br>	0: Add no license<br>	1: MIT License<br>	2: Apache License 2.0<br>	3: GNU AGPLv3<br>	4: GNU GPLv3<br>	5: GNU LGPLv3<br>	6: Mozilla Public License 2.0<br>	7: Boost Software License 1.0<br>	8: The Unlicense |
+| `author` | License author |
+| `codeowner` | Set the codeowner of the project |
+
+### `ci`
+
+| Name | Description |
+| :--- | :---------- |
+| `provider` | Set an CI pipeline provider integration<br>			Options:<br>			0: No CI<br>			1: Github<br>			2: Gitlab<br>			3: Azure DevOps |
+
+### `grpc`
+
+| Name | Description |
+| :--- | :---------- |
+| `base` | Base configuration for gRPC |
+| `grpcGateway` | Extend gRPC configuration with grpc-gateway |

embed.go

@@ -1,4 +1,3 @@
 package gotemplate
 
-//go:generate go run cmd/dotembed/main.go -target _template -o embed_gen.go -pkg gotemplate -var FS
 const Key = "_template"