chore(deps): upgrade sigs.k8s.io/controller-tools to v0.14.0 (#63)

This updates sigs.k8s.io/controller-tools to v0.14.0.

With this new version the rendering of multi lines and empty lines has
changed a little. The asciidoc and markdown renderers are 
therefore updated to take this into account.

---------

Signed-off-by: Justen Stall <justenstall@gmail.com>
Co-authored-by: Amund Tenstad <github@amund.io>
Co-authored-by: Thibault Richard <thb.krkr@gmail.com>

CONTRIBUTING.md

@@ -5,4 +5,3 @@ Thank you for your interest in crd-ref-docs. We welcome pull requests from the c
 - Ensure all new files contain the appropriate Apache-2.0 licence header.
 - If possible, add unit tests for the changes. At the very least, make sure that`./test.sh` can be run successfully after your changes.
 - Sign the [CLA](https://www.elastic.co/contributor-agreement). You only need to sign the CLA once. By signing this agreement, you give us the right to distribute your code without restriction.
-

go.mod

@@ -1,24 +1,24 @@
 module github.com/elastic/crd-ref-docs
 
-go 1.20
+go 1.21
 
 require (
 	github.com/Masterminds/sprig v2.22.0+incompatible
 	github.com/goccy/go-yaml v1.11.0
-	github.com/spf13/cobra v1.7.0
-	github.com/stretchr/testify v1.8.2
+	github.com/spf13/cobra v1.8.0
+	github.com/stretchr/testify v1.8.4
 	go.uber.org/zap v1.24.0
-	golang.org/x/tools v0.12.0
-	k8s.io/apimachinery v0.28.0
-	sigs.k8s.io/controller-tools v0.13.0
+	golang.org/x/tools v0.16.1
+	k8s.io/apimachinery v0.29.0
+	sigs.k8s.io/controller-tools v0.14.0
 )
 
 require (
 	github.com/Masterminds/goutils v1.1.1 // indirect
 	github.com/Masterminds/semver v1.5.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/fatih/color v1.15.0 // indirect
-	github.com/go-logr/logr v1.2.4 // indirect
+	github.com/fatih/color v1.16.0 // indirect
+	github.com/go-logr/logr v1.3.0 // indirect
 	github.com/gobuffalo/flect v1.0.2 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
@@ -28,7 +28,7 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
-	github.com/mattn/go-isatty v0.0.17 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
@@ -37,18 +37,18 @@ require (
 	github.com/spf13/pflag v1.0.5 // indirect
 	go.uber.org/atomic v1.10.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/crypto v0.12.0 // indirect
-	golang.org/x/mod v0.12.0 // indirect
-	golang.org/x/net v0.14.0 // indirect
-	golang.org/x/sys v0.11.0 // indirect
-	golang.org/x/text v0.12.0 // indirect
+	golang.org/x/crypto v0.16.0 // indirect
+	golang.org/x/mod v0.14.0 // indirect
+	golang.org/x/net v0.19.0 // indirect
+	golang.org/x/sys v0.15.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
 	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/apiextensions-apiserver v0.28.0 // indirect
-	k8s.io/klog/v2 v2.100.1 // indirect
-	k8s.io/utils v0.0.0-20230406110748-d93618cff8a2 // indirect
+	k8s.io/apiextensions-apiserver v0.29.0 // indirect
+	k8s.io/klog/v2 v2.110.1 // indirect
+	k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect
 	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
-	sigs.k8s.io/structured-merge-diff/v4 v4.2.3 // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
 )

renderer/asciidoctor.go

@@ -149,11 +149,14 @@ func (adr *AsciidoctorRenderer) RenderFieldDoc(text string) string {
 	lines := strings.Split(out, "\n")
 	for i := range lines {
 		lines[i] = strings.TrimSpace(lines[i])
+		// Replace newlines with hard line breaks so that newlines are rendered as expected for non-empty lines.
+		// See: https://docs.asciidoctor.org/asciidoc/latest/blocks/hard-line-breaks
+		if lines[i] != "" {
+			lines[i] = lines[i] + " +"
+		}
 	}
 
-	// Replace newlines with hard line breaks so that newlines are rendered as expected.
-	// See: https://docs.asciidoctor.org/asciidoc/latest/blocks/hard-line-breaks
-	return strings.Join(lines, " +\n\n")
+	return strings.Join(lines, "\n")
 }
 
 func (adr *AsciidoctorRenderer) RenderValidation(text string) string {

renderer/markdown.go

@@ -145,8 +145,12 @@ func (m *MarkdownRenderer) RenderFieldDoc(text string) string {
 	// so that including | in a comment does not result in wonky tables.
 	out := strings.ReplaceAll(text, "|", "\\|")
 
-	// Replace newlines with 2 line breaks so that they don't break the Markdown table formatting.
-	return strings.ReplaceAll(out, "\n", "<br /><br />")
+	// Replace newlines with 1 line break so that they don't break the Markdown table formatting.
+	out = strings.ReplaceAll(out, "\n", "<br />")
+	// and remove double newline generated for empty lines
+	// empty line is still rendered in the table, without removing the duplicate
+	// newline it would be rendered as two empty lines
+	return strings.ReplaceAll(out, "<br /><br />", "<br />")
 }
 
 func (m *MarkdownRenderer) RenderDefault(text string) string {

test/api/v1/guestbook_types.go

@@ -111,8 +111,15 @@ type GuestbookEntry struct {
 	// Time of entry
 	Time metav1.Time `json:"time,omitempty"`
 	// Comment by guest. This can be a multi-line comment.
+	// Like this one.
+	// Now let's test a list:
+	// * a
+	// * b
+	//
+	// Another isolated comment.
+	//
+	// Looks good?
 	//
-	// Just like this one.
 	// +kubebuilder:validation:Pattern=`0*[a-z0-9]*[a-z]*[0-9]*`
 	Comment string `json:"comment,omitempty"`
 	// Rating provided by the guest

test/expected.asciidoc

@@ -141,15 +141,23 @@ GuestbookEntry defines an entry in a guest book.
 [cols="20a,50a,15a,15a", options="header"]
 |===
 | Field | Description | Default | Validation
-| *`name`* __string__ | Name of the guest (pipe \| should be escaped) |  | MaxLength: 80 +
+| *`name`* __string__ | Name of the guest (pipe \| should be escaped) + |  | MaxLength: 80 +
 Pattern: `0\*[a-z0-9]*[a-z]*[0-9]` +
 
-| *`time`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta[$$Time$$]__ | Time of entry |  | 
+| *`time`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta[$$Time$$]__ | Time of entry + |  | 
 | *`comment`* __string__ | Comment by guest. This can be a multi-line comment. +
+Like this one. +
+Now let's test a list: +
+* a +
+* b +
 
-Just like this one. |  | Pattern: `0\*[a-z0-9]*[a-z]\*[0-9]*` +
 
-| *`rating`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-rating[$$Rating$$]__ | Rating provided by the guest |  | Maximum: 5 +
+Another isolated comment. +
+
+
+Looks good? + |  | Pattern: `0\*[a-z0-9]*[a-z]\*[0-9]*` +
+
+| *`rating`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-rating[$$Rating$$]__ | Rating provided by the guest + |  | Maximum: 5 +
 Minimum: 1 +
 
 |===
@@ -210,14 +218,14 @@ GuestbookSpec defines the desired state of Guestbook.
 [cols="20a,50a,15a,15a", options="header"]
 |===
 | Field | Description | Default | Validation
-| *`page`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-positiveint[$$PositiveInt$$]__ | Page indicates the page number | 1 | Minimum: 1 +
+| *`page`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-positiveint[$$PositiveInt$$]__ | Page indicates the page number + | 1 | Minimum: 1 +
 
-| *`entries`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookentry[$$GuestbookEntry$$] array__ | Entries contain guest book entries for the page |  | 
-| *`selector`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta[$$LabelSelector$$]__ | Selector selects something |  | 
-| *`headers`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookheader[$$GuestbookHeader$$] array__ | Headers contains a list of header items to include in the page |  | MaxItems: 10 +
+| *`entries`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookentry[$$GuestbookEntry$$] array__ | Entries contain guest book entries for the page + |  | 
+| *`selector`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta[$$LabelSelector$$]__ | Selector selects something + |  | 
+| *`headers`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookheader[$$GuestbookHeader$$] array__ | Headers contains a list of header items to include in the page + |  | MaxItems: 10 +
 UniqueItems: true +
 
-| *`certificateRef`* __link:https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference[$$SecretObjectReference$$]__ | CertificateRef is a reference to a secret containing a certificate |  | 
+| *`certificateRef`* __link:https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference[$$SecretObjectReference$$]__ | CertificateRef is a reference to a secret containing a certificate + |  | 
 | *`str`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-common-commonstring[$$CommonString$$]__ |  |  | 
 |===
 

test/expected.md

@@ -115,7 +115,7 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `name` _string_ | Name of the guest (pipe \| should be escaped) |  | MaxLength: 80 <br />Pattern: `0*[a-z0-9]*[a-z]*[0-9]` <br /> |
 | `time` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta)_ | Time of entry |  |  |
-| `comment` _string_ | Comment by guest. This can be a multi-line comment. <br /><br /> Just like this one. |  | Pattern: `0*[a-z0-9]*[a-z]*[0-9]*` <br /> |
+| `comment` _string_ | Comment by guest. This can be a multi-line comment.<br />Like this one.<br />Now let's test a list:<br />* a<br />* b<br /><br />Another isolated comment.<br /><br />Looks good? |  | Pattern: `0*[a-z0-9]*[a-z]*[0-9]*` <br /> |
 | `rating` _[Rating](#rating)_ | Rating provided by the guest |  | Maximum: 5 <br />Minimum: 1 <br /> |