Make output configurable (#57)

* Add new way of style the info of schema docs

* Add slug too

cmd/generate/flag.go

@@ -11,18 +11,21 @@ const (
 	flagOutputPath          = "output-path"
 	flagDocPlaceholderStart = "doc-placeholder-start"
 	flagDocPlaceholderEnd   = "doc-placeholder-end"
+	flagLayout              = "layout"
 )
 
 type flag struct {
 	outputPath          string
 	docPlaceholderStart string
 	docPlaceholderEnd   string
+	layout              string
 }
 
 func (f *flag) Init(cmd *cobra.Command) {
 	cmd.Flags().StringVarP(&f.outputPath, flagOutputPath, "o", "", "Path to file to output the generated documentation")
 	cmd.Flags().StringVar(&f.docPlaceholderStart, flagDocPlaceholderStart, "", "Placeholder string marking the start of the docs section in the output file")
 	cmd.Flags().StringVar(&f.docPlaceholderEnd, flagDocPlaceholderEnd, "", "Placeholder string marking the end of the docs section in the output file")
+	cmd.Flags().StringVarP(&f.layout, "layout", "l", "default", "Layout of the generated documentation")
 }
 
 func (f *flag) Validate() error {

cmd/generate/runner.go

@@ -48,7 +48,7 @@ func (r *runner) run(cmd *cobra.Command, args []string) error {
 
 	cli.WriteOutputF(r.stdout, "Schema: %s\n", args[0])
 
-	docs, err := generate.Generate(args[0])
+	docs, err := generate.Generate(args[0], r.flag.layout)
 	if err != nil {
 		return microerror.Mask(err)
 	}

cmd/validate/flag.go

@@ -11,18 +11,21 @@ const (
 	flagSchema              = "schema"
 	flagDocPlaceholderStart = "doc-placeholder-start"
 	flagDocPlaceholderEnd   = "doc-placeholder-end"
+	flagLayout              = "layout"
 )
 
 type flag struct {
 	schema              string
 	docPlaceholderStart string
 	docPlaceholderEnd   string
+	layout              string
 }
 
 func (f *flag) Init(cmd *cobra.Command) {
 	cmd.Flags().StringVar(&f.schema, flagSchema, "", "Path to the JSON schema file")
 	cmd.Flags().StringVar(&f.docPlaceholderStart, flagDocPlaceholderStart, "", "Placeholder string marking the start of the docs section in the output file")
 	cmd.Flags().StringVar(&f.docPlaceholderEnd, flagDocPlaceholderEnd, "", "Placeholder string marking the end of the docs section in the output file")
+	cmd.Flags().StringVarP(&f.layout, flagLayout, "l", "default", "Layout of the generated documentation")
 }
 
 func (f *flag) Validate() error {

cmd/validate/runner.go

@@ -64,7 +64,7 @@ func (r *runner) run(cmd *cobra.Command, args []string) error {
 		cli.WriteOutputF(r.stdout, "Using default placeholders '%s' and '%s'\n", readmeItem.StartPlaceholder(), readmeItem.EndPlaceholder())
 	}
 
-	err = readmeItem.Validate(r.flag.schema)
+	err = readmeItem.Validate(r.flag.schema, r.flag.layout)
 	if err != nil {
 		return err
 	}

pkg/generate/generator.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"fmt"
 	"sort"
+	"text/template"
 
 	"github.com/giantswarm/microerror"
 	"github.com/santhosh-tekuri/jsonschema/v5"
@@ -13,7 +14,7 @@ import (
 	"github.com/giantswarm/schemadocs/pkg/key"
 )
 
-func Generate(schemaPath string) (string, error) {
+func Generate(schemaPath string, layout string) (string, error) {
 	compiler := jsonschema.NewCompiler()
 	compiler.ExtractAnnotations = true
 	schema, err := compiler.Compile(schemaPath)
@@ -23,7 +24,7 @@ func Generate(schemaPath string) (string, error) {
 	}
 
 	sections := sectionsFromSchema(schema, "")
-	return toMarkdown(sections)
+	return toMarkdown(sections, layout)
 }
 
 func sectionsFromSchema(schema *jsonschema.Schema, path string) []Section {
@@ -71,15 +72,14 @@ func sectionsFromSchema(schema *jsonschema.Schema, path string) []Section {
 	return sections
 }
 
-func toMarkdown(sections []Section) (string, error) {
-	/*t, err := template.ParseFiles(
-		path.Join(pkgPath, "templates/docs.md.tpl"),
-		path.Join(pkgPath, "templates/row.md.tpl"),
-		path.Join(pkgPath, "templates/section.md.tpl"),
-	)*/
-
-	t, err := templates.GetTemplate()
-
+func toMarkdown(sections []Section, layout string) (string, error) {
+	var t *template.Template
+	var err error
+	if layout == "linear" {
+		t, err = templates.GetLinearTemplate()
+	} else {
+		t, err = templates.GetDefaultTemplate()
+	}
 	if err != nil {
 		return "", microerror.Maskf(pkgerror.DocsGenerationError, err.Error())
 	}

pkg/generate/generator_test.go

@@ -14,29 +14,39 @@ func Test_Generator(t *testing.T) {
 
 	testCases := []struct {
 		name        string
+		layout      string
 		schemaPath  string
 		outputPath  string
 		expectedErr error
 	}{
 		{
 			name:       "case 0: Generate markdown from a valid JSON schema",
+			layout:     "default",
 			schemaPath: "testdata/schema.json",
 			outputPath: "testdata/output.txt",
 		},
 		{
 			name:        "case 1: Fail to generate markdown from an existing invalid JSON schema",
+			layout:      "default",
 			schemaPath:  "testdata/schema_invalid.json",
 			expectedErr: pkgerror.InvalidSchemaFile,
 		},
 		{
 			name:        "case 2: Fail to generate markdown from a on-existent JSON schema",
+			layout:      "default",
 			expectedErr: pkgerror.InvalidSchemaFile,
 		},
+		{
+			name:       "case 3: Generate markdown from a valid JSON schema in linear layout",
+			layout:     "linear",
+			schemaPath: "testdata/schema.json",
+			outputPath: "testdata/output-linear.txt",
+		},
 	}
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
-			docs, err := Generate(tc.schemaPath)
+			docs, err := Generate(tc.schemaPath, tc.layout)
 
 			if err != nil {
 				if err != tc.expectedErr && microerror.Cause(err) != tc.expectedErr {

pkg/generate/row.go

@@ -3,6 +3,7 @@ package generate
 import (
 	"encoding/json"
 	"fmt"
+	"strings"
 
 	"github.com/santhosh-tekuri/jsonschema/v5"
 
@@ -14,6 +15,7 @@ type Row struct {
 	Name               string
 	FullPath           string
 	Title              string
+	Slug               string
 	Description        string
 	Types              []string
 	KeyPatterns        []string
@@ -101,6 +103,7 @@ func NewRow(schema *jsonschema.Schema, path string, name string, keyPatterns []s
 		Name:               name,
 		FullPath:           key.MergedPropertyPath(path, name),
 		Title:              schema.Title,
+		Slug:               strings.ReplaceAll(key.MergedPropertyPath(path, name), ".", "-"),
 		Description:        schema.Description,
 		Types:              schema.Types,
 		Primitive:          key.SchemaIsPrimitive(schema),

pkg/generate/section.go

@@ -2,13 +2,15 @@ package generate
 
 import (
 	"sort"
+	"strings"
 
 	"github.com/santhosh-tekuri/jsonschema/v5"
 )
 
 type Section struct {
 	Name        string
 	Title       string
+	Slug        string
 	Description string
 	Path        string
 	Rows        []Row
@@ -20,13 +22,15 @@ func SectionFromSchema(property *jsonschema.Schema, path, name string) Section {
 		Title:       property.Title,
 		Description: property.Description,
 		Path:        path,
+		Slug:        strings.ReplaceAll(property.Title, " ", "-"),
 		Rows:        sortedRows(RowsFromSchema(property, path, name, []string{})),
 	}
 }
 
 func NewSection(title string, rows []Row) Section {
 	return Section{
 		Title: title,
+		Slug:  strings.ReplaceAll(title, " ", "-"),
 		Rows:  sortedRows(rows),
 	}
 }

pkg/generate/templates/linear.md.tpl

@@ -0,0 +1,51 @@
+
+<div class="crd-schema-version">
+  <h2 class="headline-with-link">
+    <a class="header-link" href="#">
+      <i class="fa fa-link"></i>
+    </a>Chart Configuration Reference
+  </h2>
+
+{{- range . }}
+  <h3 class="headline-with-link">
+    <a class="header-link" href="#{{.Slug}}">
+      <i class="fa fa-link"></i>
+    </a>{{.Title}}
+  </h3>
+  {{- if .Description }}
+  <h4 class="headline-with-link">
+    <a class="header-link" href="#">
+      <i class="fa fa-link"></i>
+    </a>{{ .Description }}
+  </h4>
+  {{- end }}
+  {{- range .Rows }}
+  <div class="property depth-0">
+    <div class="property-header">
+      <h3 class="property-path headline-with-link">
+        <a class="header-link" href="#{{.Slug}}">
+          <i class="fa fa-link"></i>
+        </a>.{{- .FullPath -}}
+      </h3>
+    </div>
+    <div class="property-body">
+      <div class="property-meta">
+        {{- if .Title -}}
+        <span class="property-title">{{- .Title -}}</span><br />
+        {{- end -}}
+        {{- if ne (len .Types) 0 -}}
+          {{- range $index, $element := .Types -}}
+            {{ if $index }}, {{ end }}<span class="property-type">{{- $element }}</span>
+          {{- end -}}&nbsp;
+        {{- end }}
+      </div>
+      <div class="property-description">
+        {{- if .Description -}}
+          {{- .Description -}}
+        {{- end -}}
+      </div>
+    </div>
+  </div>
+  {{- end }}
+{{- end -}}
+</div>

pkg/generate/templates/template.go

@@ -8,13 +8,16 @@ import (
 //go:embed docs.md.tpl
 var docs string
 
+//go:embed linear.md.tpl
+var linear string
+
 //go:embed row.md.tpl
 var row string
 
 //go:embed section.md.tpl
 var section string
 
-func GetTemplate() (*template.Template, error) {
+func GetDefaultTemplate() (*template.Template, error) {
 	docsTpl, err := template.New("docs.md.tpl").Parse(docs)
 	if err != nil {
 		return nil, err
@@ -32,3 +35,12 @@ func GetTemplate() (*template.Template, error) {
 
 	return docsTpl, nil
 }
+
+func GetLinearTemplate() (*template.Template, error) {
+	docsTpl, err := template.New("linear.md.tpl").Parse(linear)
+	if err != nil {
+		return nil, err
+	}
+
+	return docsTpl, nil
+}