Add docs as part of regal new rule command (#715)

Fixes #700

Signed-off-by: Anders Eknert <anders@styra.com>

cmd/new.go

@@ -121,6 +121,10 @@ func scaffoldRule(params newRuleCommandParams) error {
 			return err
 		}
 
+		if err := createBuiltinDocs(params); err != nil {
+			return err
+		}
+
 		if err := addToDataYAML(params); err != nil {
 			return err
 		}
@@ -308,6 +312,29 @@ func scaffoldBuiltinRule(params newRuleCommandParams) error {
 	return nil
 }
 
+func createBuiltinDocs(params newRuleCommandParams) error {
+	docsDir := filepath.Join(params.output, "docs", "rules", params.category)
+
+	docTmpl, err := template.ParseFS(embeds.EmbedTemplatesFS, "templates/builtin/builtin.md.tpl")
+	if err != nil {
+		return err
+	}
+
+	docFileName := strings.ToLower(params.name) + ".md"
+
+	docFile, err := os.Create(filepath.Join(docsDir, docFileName))
+	if err != nil {
+		return err
+	}
+
+	err = docTmpl.Execute(docFile, templateValues(params))
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func templateValues(params newRuleCommandParams) TemplateValues {
 	var tmplNameValue string
 

internal/embeds/templates/builtin/builtin.md.tpl

@@ -0,0 +1,41 @@
+# {{.NameOriginal}}
+
+**Summary**: ADD DESCRIPTION HERE
+
+**Category**: {{.Category}}
+
+**Avoid**
+```rego
+package policy
+
+# ... ADD CODE TO AVOID HERE
+```
+
+**Prefer**
+```rego
+package policy
+
+# ... ADD CODE TO PREFER HERE
+```
+
+## Rationale
+
+ADD RATIONALE HERE
+
+## Configuration Options
+
+This linter rule provides the following configuration options:
+
+```yaml
+rules:
+  {{.Category}}:
+    {{.NameOriginal}}:
+      # one of "error", "warning", "ignore"
+      level: error
+```
+
+## Community
+
+If you think you've found a problem with this rule or its documentation, would like to suggest improvements, new rules,
+or just talk about Regal in general, please join us in the `#regal` channel in the Styra Community
+[Slack](https://communityinviter.com/apps/styracommunity/signup)!