add markdown rendering

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

Author: ahmetb

example-config.json

@@ -23,5 +23,6 @@
     "typeDisplayNamePrefixOverrides": {
         "k8s.io/api/": "Kubernetes ",
         "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
-    }
+    },
+    "markdownDisabled": false
 }

go.mod

@@ -2,6 +2,9 @@ module refdocs
 
 require (
 	github.com/pkg/errors v0.8.0
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/russross/blackfriday/v2 v2.0.1
+	github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
 	github.com/spf13/pflag v1.0.3 // indirect
 	golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372 // indirect
 	k8s.io/gengo v0.0.0-20181113154421-fd15ee9cc2f7

go.sum

@@ -1,5 +1,11 @@
 github.com/pkg/errors v0.8.0 h1:WdK/asTD0HN+q6hsWO3/vpuAkAr+tw6aNJNDFFf0+qw=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q=
+github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
+github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
 github.com/spf13/pflag v1.0.3 h1:zPAT6CGy6wXeQ7NtTnaTerfKOsV6V6F8agHXFiazDkg=
 github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
 golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372 h1:zWPUEY/PjVHT+zO3L8OfkjrtIjf55joTxn/RQP/AjOI=

main.go

@@ -21,6 +21,7 @@ import (
 	"unicode"
 
 	"github.com/pkg/errors"
+	"github.com/russross/blackfriday/v2"
 	"k8s.io/gengo/parser"
 	"k8s.io/gengo/types"
 	"k8s.io/klog"
@@ -52,6 +53,9 @@ type generatorConfig struct {
 	// TypeDisplayNamePrefixOverrides is a mapping of how to override displayed
 	// name for types with certain prefixes with what value.
 	TypeDisplayNamePrefixOverrides map[string]string `json:"typeDisplayNamePrefixOverrides"`
+
+	// MarkdownDisabled controls markdown rendering for comment lines.
+	MarkdownDisabled bool `json:"markdownDisabled"`
 }
 
 type externalPackage struct {
@@ -252,15 +256,23 @@ func isLocalType(t *types.Type) bool {
 	return false
 }
 
-func showComments(s []string) string {
+func renderComments(s []string, markdown bool) string {
 	s = filterCommentTags(s)
-	return strings.Join(s, "\n")
+	doc := strings.Join(s, "\n")
+
+	if markdown {
+		// TODO(ahmetb): when a comment includes stuff like "http://<service>"
+		// we treat this as a HTML tag with markdown renderer below. solve this.
+		return string(blackfriday.Run([]byte(doc)))
+	}
+	return nl2br(doc)
 }
 
+func safe(s string) template.HTML { return template.HTML(s) }
+
 func nl2br(s string) string {
 	return strings.Replace(s, "\n\n", string(template.HTML("<br/><br/>")), -1)
 }
-func safe(s string) template.HTML { return template.HTML(s) }
 
 func hiddenMember(m types.Member, c generatorConfig) bool {
 	for _, v := range c.HiddenMemberFields {
@@ -484,8 +496,7 @@ func render(w io.Writer, pkgs []*types.Package, config generatorConfig) error {
 		"typeIdentifier":     func(t *types.Type) string { return typeIdentifier(t, config) },
 		"typeDisplayName":    func(t *types.Type) string { return typeDisplayName(t, config) },
 		"visibleTypes":       func(t []*types.Type) []*types.Type { return visibleTypes(t, config) },
-		"showComments":       showComments,
-		"nl2br":              nl2br,
+		"renderComments":     func(s []string) string { return renderComments(s, !config.MarkdownDisabled) },
 		"packageDisplayName": packageDisplayName,
 		"apiGroup":           func(t *types.Type) string { return apiVersions[t.Name.Package] },
 		"linkForType": func(t *types.Type) string {

template/members.tpl

@@ -26,7 +26,7 @@
             <em>(Optional)</em>
         {{ end }}
 
-        {{ safe (nl2br (showComments .CommentLines)) }}
+        {{ safe (renderComments .CommentLines) }}
 
     {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
         Refer to the Kubernetes API documentation for the fields of the

template/pkg.tpl

@@ -14,7 +14,7 @@ table, td, th {
 
     {{ with .DocComments }}
     <p>
-        {{ showComments . }}
+        {{ safe (renderComments .) }}
     </p>
     {{ end }}
 
@@ -30,23 +30,6 @@ table, td, th {
     </ul>
 
     {{ range (visibleTypes (sortedTypes .Types))}}
-        <h3 id="{{ .Name.Name }}">
-            {{- .Name.Name }}
-            {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
-        </h3>
-        {{ with (typeReferences .) }}
-            <p>
-                (<em>Appears on:</em>
-                {{- $prev := "" -}}
-                {{- range . -}}
-                    {{- if $prev -}}, {{ end -}}
-                    {{ $prev = . }}
-                    <a href="#{{ typeIdentifier . }}">{{ typeDisplayName . }}</a>
-                {{- end -}}
-                )
-            </p>
-        {{ end }}
-
         {{ template "type" .  }}
     {{ end }}
     <hr/>

template/type.tpl

@@ -1,7 +1,25 @@
 {{ define "type" }}
 
+<h3 id="{{ .Name.Name }}">
+    {{- .Name.Name }}
+    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
+</h3>
+{{ with (typeReferences .) }}
+    <p>
+        (<em>Appears on:</em>
+        {{- $prev := "" -}}
+        {{- range . -}}
+            {{- if $prev -}}, {{ end -}}
+            {{ $prev = . }}
+            <a href="#{{ typeIdentifier . }}">{{ typeDisplayName . }}</a>
+        {{- end -}}
+        )
+    </p>
+{{ end }}
+
+
 <p>
-    {{ safe (nl2br (showComments .CommentLines)) }}
+    {{ safe (renderComments .CommentLines) }}
 </p>
 
 {{ if .Members }}