feat: generate the documentation file

Signed-off-by: Alexandre Couedelo <[email protected]>

document/metadata.go

@@ -42,32 +42,35 @@ func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, erro
 }
 
 type Section struct {
-	H          int
-	Path       string
-	Annotation *ast.Annotations
+	H           string
+	Path        string
+	Annotations *ast.Annotations
 }
 
 func (s Section) Equal(s2 Section) bool {
-	if s.H == s2.H && s.Path == s2.Path {
+	if s.H == s2.H &&
+		s.Path == s2.Path &&
+		s.Annotations.Title == s2.Annotations.Title {
 		return true
 	}
 
 	return false
 }
 
+// GetDocument generate a more convenient struct that can be used to generate the doc
 func GetDocument(as ast.FlatAnnotationsRefSet) []Section {
 
 	var s []Section
 
 	for _, entry := range as {
 
-		depth := len(entry.Path) - 1
+		depth := strings.Repeat("#", len(entry.Path))
 		path := strings.TrimPrefix(entry.Path.String(), "data.")
 
 		s = append(s, Section{
-			H:          depth,
-			Path:       path,
-			Annotation: entry.Annotations,
+			H:           depth,
+			Path:        path,
+			Annotations: entry.Annotations,
 		})
 	}
 

document/metadata_test.go

@@ -111,8 +111,11 @@ p := 7
 			},
 			want: []Section{
 				{
-					H:    2,
+					H:    "##",
 					Path: "foo.p",
+					Annotations: &ast.Annotations{
+						Title: "My Rule P",
+					},
 				},
 			},
 		},
@@ -135,23 +138,23 @@ q := 8
 			},
 			want: []Section{
 				{
-					H:    1,
+					H:    "##",
 					Path: "foo",
-					Annotation: &ast.Annotations{
-						Title: "My Rule P",
+					Annotations: &ast.Annotations{
+						Title: "My Package foo",
 					},
 				},
 				{
-					H:    2,
+					H:    "###",
 					Path: "foo.p",
-					Annotation: &ast.Annotations{
+					Annotations: &ast.Annotations{
 						Title: "My Rule P",
 					},
 				},
 				{
-					H:    2,
+					H:    "###",
 					Path: "foo.q",
-					Annotation: &ast.Annotations{
+					Annotations: &ast.Annotations{
 						Title: "My Rule Q",
 					},
 				},

document/resources/document.md

@@ -0,0 +1,17 @@
+# Policies
+{{ range . }}
+{{ .H }} {{ .Path }} - {{ .Annotations.Title }}
+
+{{ .Annotations.Description }}
+{{- if .Annotations.RelatedResources }}
+
+Related Resources:
+{{ range .Annotations.RelatedResources }}
+{{- if .Description -}}
+* [{{.Description}}]({{ .Ref }})
+{{- else }}
+* {{ .Ref }}
+{{ end -}}
+{{- end -}}
+{{ end }}
+{{ end }}

document/template.go

@@ -0,0 +1,37 @@
+package document
+
+import (
+	"embed"
+	"io"
+	"io/fs"
+	"text/template"
+)
+
+//go:embed resources/*
+var resources embed.FS
+
+func generateDocument(out io.Writer, s []Section) error {
+
+	err := renderTemplate(resources, "resources/document.md", s, out)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func renderTemplate(fs fs.FS, tpl string, args interface{}, out io.Writer) error {
+	// read the template
+	t, err := template.ParseFS(fs, tpl)
+	if err != nil {
+		return err
+	}
+
+	// we render the template
+	err = t.Execute(out, args)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}

document/template_test.go

@@ -0,0 +1,49 @@
+package document
+
+import (
+	"bytes"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"os"
+	"testing"
+)
+
+func Test_generateDocument(t *testing.T) {
+	tests := []struct {
+		name     string
+		testdata string
+		wantOut  string
+		wantErr  bool
+	}{
+		{
+			name:     "Nested packages",
+			testdata: "./testdata/foo",
+			wantOut:  "./testdata/doc/foo.md",
+			wantErr:  false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(
+			tt.name, func(t *testing.T) {
+				as, err := ParseRegoWithAnnotations(tt.testdata)
+				assert.NoError(t, err)
+
+				s := GetDocument(as)
+
+				gotOut := &bytes.Buffer{}
+				err = generateDocument(gotOut, s)
+				if (err != nil) != tt.wantErr {
+					t.Errorf("GenVariableDoc() error = %v, wantErr %v", err, tt.wantErr)
+					return
+				}
+
+				wantOut, err := os.ReadFile(tt.wantOut)
+				require.NoError(t, err)
+				assert.Equal(t, string(wantOut), gotOut.String())
+
+				// un comment this to generate the golden file when changing the template
+				//os.WriteFile(tt.wantOut+".golden", gotOut.Bytes(), 0644)
+			},
+		)
+	}
+}

document/testdata/doc/foo.md

@@ -1,9 +1,23 @@
-# Policies - bar
+# Policies
 
-## Rules
+## foo - My package foo
 
-### My Rule P
+the package with rule A and subpackage bar
+
+### foo.a - My Rule A
+
+the rule A = 3
+
+Related Resources:
+
+* https://example.com
+* [Yet another link](https://example.com/more)
+
+### foo.bar - My package bar
+
+The package with rule P
+
+#### foo.bar.p - My Rule P
+
+the Rule P = 7
 
-```opa
-p := 7
-```

document/testdata/foo/bar/bizz.rego

@@ -1,8 +1,9 @@
 # METADATA
 # title: My package bar
-# description: A couple of useful rules
+# description: The package with rule P
 package foo.bar
 
 # METADATA
 # title: My Rule P
+# description: the Rule P = 7
 p := 7

document/testdata/foo/base.rego

@@ -1,10 +1,16 @@
 # METADATA
 # title: My package foo
+# description: the package with rule A and subpackage bar
 # scope: subpackages
 # organizations:
 # - Acme Corp.
 package foo
 
 # METADATA
 # title: My Rule A
+# description: the rule A = 3
+# related_resources:
+# - ref: https://example.com
+# - ref: https://example.com/more
+#   description: Yet another link
 a := 3