Escape pipe characters in field documentation for asciidoc (elastic#17)

Escape the pipe character, which has special meaning for asciidoc as a way to format tables, so that including | in a field comment does not result in wonky tables.
airycanon · Jan 24, 2022 · efa87ff · efa87ff
1 parent a642cb2
commit efa87ff
Show file tree

Hide file tree

Showing 5 changed files with 11 additions and 4 deletions.
diff --git a/renderer/asciidoctor.go b/renderer/asciidoctor.go
@@ -83,6 +83,7 @@ func (adr *AsciidoctorRenderer) ToFuncMap() template.FuncMap {
 		"SafeID":             adr.SafeID,
 		"ShouldRenderType":   adr.ShouldRenderType,
 		"TypeID":             adr.TypeID,
+		"RenderFieldDoc":     adr.RenderFieldDoc,
 	}
 }
 
@@ -140,3 +141,9 @@ func (adr *AsciidoctorRenderer) RenderGVLink(gv types.GroupVersionDetails) strin
 func (adr *AsciidoctorRenderer) RenderAnchorID(id string) string {
 	return fmt.Sprintf("%s%s", asciidocAnchorPrefix, adr.SafeID(id))
 }
+
+func (adr *AsciidoctorRenderer) RenderFieldDoc(text string) string {
+	// escape the pipe character, which has special meaning for asciidoc as a way to format tables,
+	// so that including | in a comment does not result in wonky tables
+	return strings.ReplaceAll(text, "|", "\\|")
+}
diff --git a/templates/asciidoctor/type_members.tpl b/templates/asciidoctor/type_members.tpl
@@ -3,6 +3,6 @@
 {{- if eq $field.Name "metadata" -}}
 Refer to Kubernetes API documentation for fields of `metadata`.
 {{ else -}}
-{{ $field.Doc }}
+{{ asciidocRenderFieldDoc $field.Doc }}
 {{- end -}}
 {{- end -}}
diff --git a/test/api/v1/guestbook_types.go b/test/api/v1/guestbook_types.go
@@ -35,7 +35,7 @@ type GuestbookSpec struct {
 
 // GuestbookEntry defines an entry in a guest book.
 type GuestbookEntry struct {
-	// Name of the guest
+	// Name of the guest (pipe | should be escaped)
 	Name string `json:"name,omitempty"`
 	// Time of entry
 	Time metav1.Time `json:"time,omitempty"`

diff --git a/test/expected.asciidoc b/test/expected.asciidoc
@@ -53,7 +53,7 @@ GuestbookEntry defines an entry in a guest book.
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`name`* __string__ | Name of the guest
+| *`name`* __string__ | Name of the guest (pipe \| should be escaped)
 | *`time`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#time-v1-meta[$$Time$$]__ | Time of entry
 | *`comment`* __string__ | Comment by guest
 | *`rating`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-rating[$$Rating$$]__ | Rating provided by the guest

diff --git a/test/expected.md b/test/expected.md
@@ -42,7 +42,7 @@ _Appears in:_
 
 | Field | Description |
 | --- | --- |
-| `name` _string_ | Name of the guest |
+| `name` _string_ | Name of the guest (pipe | should be escaped) |
 | `time` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#time-v1-meta)_ | Time of entry |
 | `comment` _string_ | Comment by guest |
 | `rating` _[Rating](#rating)_ | Rating provided by the guest |