fix(internal/godocfx): Use default html rendering (#6802)

The previous setup was rendering doc headings as H1s. Now that the default GoDoc supports links and lists, we can use it directly. As a result, we can delete the third_party copy of the go/doc package and the custom goldmark plugin. `ToMarkdown` was added in #3816.
googleapis · Oct 3, 2022 · ec2ad2f · ec2ad2f
1 parent 81e52e5
commit ec2ad2f
Show file tree

Hide file tree

Showing 20 changed files with 184 additions and 4,166 deletions.
diff --git a/internal/godocfx/go.mod b/internal/godocfx/go.mod
@@ -8,7 +8,6 @@ require (
 	cloud.google.com/go/datastore v1.8.0
 	cloud.google.com/go/storage v1.27.0
 	github.com/google/go-cmp v0.5.8
-	github.com/yuin/goldmark v1.4.12
 	golang.org/x/sync v0.0.0-20220601150217-0de741cfad7f
 	golang.org/x/tools v0.1.11
 	gopkg.in/yaml.v2 v2.4.0

diff --git a/internal/godocfx/go.sum b/internal/godocfx/go.sum
@@ -160,8 +160,6 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.1/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
-github.com/yuin/goldmark v1.4.12 h1:6hffw6vALvEDqJ19dOJvJKOoAOKe4NDaTqvd2sktGN0=
-github.com/yuin/goldmark v1.4.12/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opencensus.io v0.23.0 h1:gqCw0LfLxScz8irSi8exQc7fyQ0fKQU/qnC/X8+V/1M=
 go.opencensus.io v0.23.0/go.mod h1:XItmlyltB5F7CS4xOC1DcqMoFqwtC6OG2xF7mCv7P7E=
 go.opentelemetry.io/proto/otlp v0.7.0/go.mod h1:PqfVotwruBrMGOCsRd/89rSnXhoiJIqeYNgFYFoEGnI=

diff --git a/internal/godocfx/goldmark-codeblock/codeblock.go b/internal/godocfx/goldmark-codeblock/codeblock.go
diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go
@@ -27,6 +27,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
+	"go/doc"
 	"go/format"
 	"go/printer"
 	"go/token"
@@ -39,12 +40,8 @@ import (
 	"strings"
 	"sync"
 
-	goldmarkcodeblock "cloud.google.com/go/internal/godocfx/goldmark-codeblock"
 	"cloud.google.com/go/internal/godocfx/pkgload"
-	"cloud.google.com/go/third_party/go/doc"
 	"cloud.google.com/go/third_party/pkgsite"
-	"github.com/yuin/goldmark"
-	"github.com/yuin/goldmark/renderer/html"
 	"golang.org/x/tools/go/packages"
 )
 
@@ -174,7 +171,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 			UID:             pi.Doc.ImportPath,
 			Name:            pi.Doc.ImportPath,
 			ID:              pi.Doc.Name,
-			Summary:         toHTML(pi.Doc.Doc),
+			Summary:         toHTML(pi.Doc, pi.Doc.Doc),
 			Langs:           onlyGo,
 			Type:            "package",
 			Examples:        processExamples(pi.Doc.Examples, pi.Fset),
@@ -622,23 +619,19 @@ func buildTOC(mod string, pis []pkgload.Info, extraFiles []extraFile) tableOfCon
 	return toc
 }
 
-func toHTML(s string) string {
+func toHTML(p *doc.Package, s string) string {
 	buf := &bytes.Buffer{}
 	// First, convert to Markdown.
-	doc.ToMarkdown(buf, s, nil)
-
-	// Then, handle Markdown stuff, like lists and links.
-	md := goldmark.New(goldmark.WithRendererOptions(html.WithUnsafe()), goldmark.WithExtensions(goldmarkcodeblock.CodeBlock))
-	mdBuf := &bytes.Buffer{}
-	if err := md.Convert(buf.Bytes(), mdBuf); err != nil {
-		panic(err)
-	}
+	buf.Write(p.HTML(s))
 
 	// Replace * with &#42; to avoid confusing the DocFX Markdown processor,
 	// which sometimes interprets * as <em>.
-	result := string(bytes.ReplaceAll(mdBuf.Bytes(), []byte("*"), []byte("&#42;")))
+	b := bytes.ReplaceAll(buf.Bytes(), []byte("*"), []byte("&#42;"))
 
-	return result
+	// Add prettyprint class to all pre elements.
+	b = bytes.ReplaceAll(b, []byte("<pre>"), []byte("<pre class=\"prettyprint\">"))
+
+	return string(b)
 }
 
 func hasPrefix(s string, prefixes []string) bool {

diff --git a/internal/godocfx/pkgload/load.go b/internal/godocfx/pkgload/load.go
@@ -17,13 +17,13 @@ package pkgload
 import (
 	"fmt"
 	"go/ast"
+	"go/doc"
 	"go/parser"
 	"go/token"
 	"sort"
 	"strconv"
 	"strings"
 
-	"cloud.google.com/go/third_party/go/doc"
 	"golang.org/x/tools/go/packages"
 )