From efa87ff888e6df595d224a5ab967b88271933dda Mon Sep 17 00:00:00 2001
From: Margo Crawford <margaretmcrawf@gmail.com>
Date: Mon, 24 Jan 2022 09:14:22 -0800
Subject: [PATCH] Escape pipe characters in field documentation for asciidoc
 (#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.
---
 renderer/asciidoctor.go                | 7 +++++++
 templates/asciidoctor/type_members.tpl | 2 +-
 test/api/v1/guestbook_types.go         | 2 +-
 test/expected.asciidoc                 | 2 +-
 test/expected.md                       | 2 +-
 5 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/renderer/asciidoctor.go b/renderer/asciidoctor.go
index 61b04ad..0f71bd9 100644
--- 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
index 89f6db0..7356dab 100644
--- 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
index b8a8279..e92a647 100644
--- 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
index a6dded0..a3cf2c3 100644
--- 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
index a276847..923144d 100644
--- 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 |