From 46b63f3ffddc9657bc2c45fb116dc49c0b381a34 Mon Sep 17 00:00:00 2001 From: Jonathan Amsterdam Date: Fri, 27 Mar 2026 16:00:47 -0400 Subject: internal/api: add htmlRenderer Change-Id: Ib25c913ce7641dea58e2eefb6d65f5cc7dec813a Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/760820 Reviewed-by: Hyang-Ah Hana Kim Reviewed-by: Ethan Lee kokoro-CI: kokoro LUCI-TryBot-Result: Go LUCI --- internal/api/render.go | 79 ++++++++++++++++++++++++++++++++++++++- internal/api/render_test.go | 1 + internal/api/testdata/html.golden | 75 +++++++++++++++++++++++++++++++++++++ 3 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 internal/api/testdata/html.golden diff --git a/internal/api/render.go b/internal/api/render.go index 656a8405..8654de2c 100644 --- a/internal/api/render.go +++ b/internal/api/render.go @@ -2,6 +2,10 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. +// TODO(jba)? Consider rendering notes separately. Now they appear +// with the doc for each symbol, which is probably better for LLMs, +// but be open to evidence to the contrary. + package api import ( @@ -11,6 +15,7 @@ import ( "go/doc/comment" "go/format" "go/token" + "html" "io" "slices" "strings" @@ -25,7 +30,7 @@ import ( type renderer interface { start(*doc.Package) end() error - // startSection start a section, like the one for functions. + // startSection starts a section, like the one for functions. startSection(name string) endSection() @@ -94,6 +99,7 @@ func (r *textRenderer) emit(comment string, node ast.Node) { r.printf("\n") } +// TODO(jba): consolidate this function to avoid duplication. func (r *textRenderer) printf(format string, args ...any) { if r.err != nil { return @@ -175,6 +181,77 @@ func (r *markdownRenderer) printf(format string, args ...any) { } } +type htmlRenderer struct { + fset *token.FileSet + w io.Writer + pkg *doc.Package + parser *comment.Parser + printer *comment.Printer + caser cases.Caser + err error +} + +func (r *htmlRenderer) start(pkg *doc.Package) { + r.pkg = pkg + r.parser = pkg.Parser() + r.printer = pkg.Printer() + r.printer.HeadingLevel = 3 + r.caser = cases.Title(language.English) + + r.printf("

package %s

\n", pkg.Name) + if pkg.Doc != "" { + r.printf("\n") + _, err := r.w.Write(r.printer.HTML(r.parser.Parse(pkg.Doc))) + if err != nil { + r.err = err + } + } + r.printf("\n") +} + +func (r *htmlRenderer) end() error { return r.err } + +func (r *htmlRenderer) startSection(name string) { + if name == "" { + return + } + r.printf("

%s

\n\n", r.caser.String(name)) +} + +func (r *htmlRenderer) endSection() {} + +func (r *htmlRenderer) emit(comment string, node ast.Node) { + if r.err != nil { + return + } + var buf strings.Builder + err := format.Node(&buf, r.fset, node) + if err != nil { + r.err = err + return + } + r.printf("
%s
\n", html.EscapeString(buf.String())) + formatted := r.printer.HTML(r.parser.Parse(comment)) + if len(formatted) > 0 { + _, err = r.w.Write(formatted) + if err != nil { + r.err = err + return + } + } + r.printf("\n") +} + +func (r *htmlRenderer) printf(format string, args ...any) { + if r.err != nil { + return + } + _, err := fmt.Fprintf(r.w, format, args...) + if err != nil { + r.err = err + } +} + // renderDoc renders the documentation for dpkg using the given renderer. // TODO(jba): support examples. func renderDoc(dpkg *doc.Package, r renderer) error { diff --git a/internal/api/render_test.go b/internal/api/render_test.go index d163b26d..14e06d6d 100644 --- a/internal/api/render_test.go +++ b/internal/api/render_test.go @@ -65,4 +65,5 @@ func TestRenderDoc(t *testing.T) { check(t, "text", &textRenderer{fset: decoded.Fset, w: &sb}) check(t, "markdown", &markdownRenderer{fset: decoded.Fset, w: &sb}) + check(t, "html", &htmlRenderer{fset: decoded.Fset, w: &sb}) } diff --git a/internal/api/testdata/html.golden b/internal/api/testdata/html.golden new file mode 100644 index 00000000..d77b329c --- /dev/null +++ b/internal/api/testdata/html.golden @@ -0,0 +1,75 @@ +

package pkg

+ +

Package pkg has every form of declaration. +

Heading

+

Search Google for details. +

+ + +

Constants

+ +
const (
+	X = 1
+	Y = 2
+)
+

Several constants. + +

const C = 1
+

C is a shorthand for 1. + +

Variables

+ +
var V = 2
+

V is a variable. + +

Functions

+ +
func Add(x int) int
+

Add adds 1 to x. + +

func F()
+

F is a function. + +

Types

+ +
type A int
+ +
type B bool
+ +
type I1 interface {
+	M1()
+}
+

I1 is an interface. + +

type I2 interface {
+	I1
+	M2()
+}
+ +
type S1 struct {
+	F int // field
+}
+

S1 is a struct. + +

type S2 struct {
+	S1
+	G int
+}
+

S2 is another struct. + +

type T int
+

T is a type. + +

const CT T = 3
+

CT is a typed constant. +They appear after their type. + +

func TF() T
+

TF is a constructor for T. + +

func (T) M()
+

M is a method of T. +BUG(xxx): this verifies that notes are rendered. \ No newline at end of file -- cgit v1.3