Rendering issues for generated API docs

[Ashley Davis]

We run gen-crd-api-reference-docs in "markdown" mode, where it will process doc comments as markdown, but it's buggy and incorrect for some links.

An example is this line which is converted to:

<p>Server is the connection address for the Vault server, e.g: &ldquo;<a href="https://vault.example.com:8200&quot;">https://vault.example.com:8200&rdquo;</a>.</p>

That invalid link ends up getting parsed a second time (when we render the file using next.js) and we end up creating a second <a> inside the first <a> which is even more invalid. That then confuses React which expects only valid HTML, and it prints lots of errors (but renders OK, I think).

A possible solution would be to parse all of the docs comments as HTML, but that's not possible because some of them are invalid HTML and in any case a lot of them use Markdown so it'd be tedious to change it for all CRDs on all branches.

---

I created an example using just blackfriday which illustrates the error:

package main

import (
	"fmt"

	"github.com/russross/blackfriday/v2"
)

func main() {
	fmt.Println(string(blackfriday.Run([]byte(`for example: "https://example.com"`))))
}

This produces this output:

<p>for example: &ldquo;<a href="https://example.com&quot;">https://example.com&rdquo;</a></p>

On both the version of blackfriday used by gen-crd-api-reference-docs and on the latest version

[Ashley Davis]

This is an upstream bug in a dependency of the thing we actually use... and blackfriday doesn't seem to be maintained. A fix upstream seems difficult to rely on, so we might have to work around this.

Either:

1. In postprocessing, we strip these broken links.
2. We change the URLs in cert-manager (and wait for it to break again)
3. We fork / fix upstream

[Ashley Davis]

Note: In #1170 we add trust-manager API doc generation with crdoc (https://github.com/fybrik/crdoc/) which doesn't seem to have the same problems with invalid HTML generation. It might not be a universal solution for everything but it might be better to use that for cert-manager, too.