internal/api: add support for examples

renderDoc now includes examples.

It has an option to omit examples, if we decide to omit them
in order to reduce the context load.

Change-Id: Ieaa411fe09b439f51aac7d49195cd5791a20d0d8
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/761000
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
Reviewed-by: Ethan Lee <ethanalee@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>

7 files changed, 538 insertions, 16 deletions

diff --git a/internal/api/testdata/examples.go b/internal/api/testdata/examples.go
new file mode 100644
index 00000000..93baaa17
--- /dev/null
+++ b/internal/api/testdata/examples.go
@@ -0,0 +1,14 @@
+// Copyright 2026 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package examples
+
+// F is a function.
+func F() {}
+
+// T is a type.
+type T struct{}
+
+// M is a method.
+func (T) M() {}
diff --git a/internal/api/testdata/html-examples.golden b/internal/api/testdata/html-examples.golden
new file mode 100644
index 00000000..fd6e0682
--- /dev/null
+++ b/internal/api/testdata/html-examples.golden
@@ -0,0 +1,155 @@
+<h1>package pkg</h1>
+
+<p>Package pkg has every form of declaration.
+<h3 id="hdr-Heading">Heading</h3>
+<p>Search <a href="https://google.com">Google</a> for details.
+<h3 id="hdr-Links">Links</h3>
+<ul>
+<li>pkgsite repo, <a href="https://go.googlesource.com/pkgsite">https://go.googlesource.com/pkgsite</a>
+<li>Play with Go, <a href="https://play-with-go.dev">https://play-with-go.dev</a>
+</ul>
+
+<h4>Example</h4>
+
+<pre><code>
+{
+	fmt.Println("Package example")
+
+}
+</code></pre>
+Output:
+
+<pre><code>
+Package example
+
+</code></pre>
+
+<h2>Constants</h2>
+
+<pre><code>const (
+	X = 1
+	Y = 2
+)</code></pre>
+<p>Several constants.
+
+<pre><code>const C = 1</code></pre>
+<p>C is a shorthand for 1.
+
+<h2>Variables</h2>
+
+<pre><code>var V = 2</code></pre>
+<p>V is a variable.
+
+<h2>Functions</h2>
+
+<pre><code>func Add(x int) int</code></pre>
+<p>Add adds 1 to x.
+
+<pre><code>func F()</code></pre>
+<p>F is a function.
+
+<h4>Example</h4>
+
+<pre><code>
+{
+	pkg.F()
+	fmt.Println("F example")
+
+}
+</code></pre>
+Output:
+
+<pre><code>
+F example
+
+</code></pre>
+
+<h4>Example (second)</h4>
+
+<pre><code>
+{
+	pkg.F()
+	fmt.Println("F second example")
+
+}
+</code></pre>
+Output:
+
+<pre><code>
+F second example
+
+</code></pre>
+
+<h2>Types</h2>
+
+<pre><code>type A int</code></pre>
+
+<pre><code>type B bool</code></pre>
+
+<pre><code>type I1 interface {
+	M1()
+}</code></pre>
+<p>I1 is an interface.
+
+<pre><code>type I2 interface {
+	I1
+	M2()
+}</code></pre>
+
+<pre><code>type S1 struct {
+	F int // field
+}</code></pre>
+<p>S1 is a struct.
+
+<pre><code>type S2 struct {
+	S1
+	G int
+}</code></pre>
+<p>S2 is another struct.
+
+<pre><code>type T int</code></pre>
+<p>T is a type.
+
+<h4>Example</h4>
+
+<pre><code>
+{
+	_ = pkg.T(0)
+	fmt.Println("T example")
+
+}
+</code></pre>
+Output:
+
+<pre><code>
+T example
+
+</code></pre>
+
+<pre><code>const CT T = 3</code></pre>
+<p>CT is a typed constant.
+They appear after their type.
+
+<pre><code>func TF() T</code></pre>
+<p>TF is a constructor for T.
+
+<pre><code>func (T) M()</code></pre>
+<p>M is a method of T.
+BUG(xxx): this verifies that notes are rendered.
+
+<h4>Example</h4>
+
+<pre><code>
+{
+	var t pkg.T
+	t.M()
+	fmt.Println("M example")
+
+}
+</code></pre>
+Output:
+
+<pre><code>
+M example
+
+</code></pre>
diff --git a/internal/api/testdata/html.golden b/internal/api/testdata/html.golden
index d77b329c..dac7514b 100644
--- a/internal/api/testdata/html.golden
+++ b/internal/api/testdata/html.golden
@@ -72,4 +72,4 @@ They appear after their type.
 
 <pre><code>func (T) M()</code></pre>
 <p>M is a method of T.
-BUG(xxx): this verifies that notes are rendered.
\ No newline at end of file
+BUG(xxx): this verifies that notes are rendered.
diff --git a/internal/api/testdata/markdown-examples.golden b/internal/api/testdata/markdown-examples.golden
new file mode 100644
index 00000000..c552629b
--- /dev/null
+++ b/internal/api/testdata/markdown-examples.golden
@@ -0,0 +1,185 @@
+# package pkg
+
+Package pkg has every form of declaration.
+
+### Heading {#hdr-Heading}
+
+Search [Google](https://google.com) for details.
+
+### Links {#hdr-Links}
+
+  - pkgsite repo, [https://go.googlesource.com/pkgsite](https://go.googlesource.com/pkgsite)
+  - Play with Go, [https://play-with-go.dev](https://play-with-go.dev)
+
+#### Example
+
+```go
+{
+	fmt.Println("Package example")
+
+}
+```
+Output:
+
+```
+Package example
+
+```
+
+## Constants
+
+```go
+const (
+	X = 1
+	Y = 2
+)
+```
+Several constants.
+
+```go
+const C = 1
+```
+C is a shorthand for 1.
+
+## Variables
+
+```go
+var V = 2
+```
+V is a variable.
+
+## Functions
+
+```go
+func Add(x int) int
+```
+Add adds 1 to x.
+
+```go
+func F()
+```
+F is a function.
+
+#### Example
+
+```go
+{
+	pkg.F()
+	fmt.Println("F example")
+
+}
+```
+Output:
+
+```
+F example
+
+```
+
+#### Example (second)
+
+```go
+{
+	pkg.F()
+	fmt.Println("F second example")
+
+}
+```
+Output:
+
+```
+F second example
+
+```
+
+## Types
+
+```go
+type A int
+```
+
+```go
+type B bool
+```
+
+```go
+type I1 interface {
+	M1()
+}
+```
+I1 is an interface.
+
+```go
+type I2 interface {
+	I1
+	M2()
+}
+```
+
+```go
+type S1 struct {
+	F int // field
+}
+```
+S1 is a struct.
+
+```go
+type S2 struct {
+	S1
+	G int
+}
+```
+S2 is another struct.
+
+```go
+type T int
+```
+T is a type.
+
+#### Example
+
+```go
+{
+	_ = pkg.T(0)
+	fmt.Println("T example")
+
+}
+```
+Output:
+
+```
+T example
+
+```
+
+```go
+const CT T = 3
+```
+CT is a typed constant. They appear after their type.
+
+```go
+func TF() T
+```
+TF is a constructor for T.
+
+```go
+func (T) M()
+```
+M is a method of T. BUG(xxx): this verifies that notes are rendered.
+
+#### Example
+
+```go
+{
+	var t pkg.T
+	t.M()
+	fmt.Println("M example")
+
+}
+```
+Output:
+
+```
+M example
+
+```
diff --git a/internal/api/testdata/markdown.golden b/internal/api/testdata/markdown.golden
index 205546d0..8e19e5db 100644
--- a/internal/api/testdata/markdown.golden
+++ b/internal/api/testdata/markdown.golden
@@ -13,7 +13,7 @@ Search [Google](https://google.com) for details.
 
 ## Constants
 
-```
+```go
 const (
 	X = 1
 	Y = 2
@@ -21,62 +21,62 @@ const (
 ```
 Several constants.
 
-```
+```go
 const C = 1
 ```
 C is a shorthand for 1.
 
 ## Variables
 
-```
+```go
 var V = 2
 ```
 V is a variable.
 
 ## Functions
 
-```
+```go
 func Add(x int) int
 ```
 Add adds 1 to x.
 
-```
+```go
 func F()
 ```
 F is a function.
 
 ## Types
 
-```
+```go
 type A int
 ```
 
-```
+```go
 type B bool
 ```
 
-```
+```go
 type I1 interface {
 	M1()
 }
 ```
 I1 is an interface.
 
-```
+```go
 type I2 interface {
 	I1
 	M2()
 }
 ```
 
-```
+```go
 type S1 struct {
 	F int // field
 }
 ```
 S1 is a struct.
 
-```
+```go
 type S2 struct {
 	S1
 	G int
@@ -84,22 +84,22 @@ type S2 struct {
 ```
 S2 is another struct.
 
-```
+```go
 type T int
 ```
 T is a type.
 
-```
+```go
 const CT T = 3
 ```
 CT is a typed constant. They appear after their type.
 
-```
+```go
 func TF() T
 ```
 TF is a constructor for T.
 
-```
+```go
 func (T) M()
 ```
 M is a method of T. BUG(xxx): this verifies that notes are rendered.
diff --git a/internal/api/testdata/pkg_test.go b/internal/api/testdata/pkg_test.go
new file mode 100644
index 00000000..4697bec4
--- /dev/null
+++ b/internal/api/testdata/pkg_test.go
@@ -0,0 +1,46 @@
+// Copyright 2026 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package pkg_test
+
+import (
+	"fmt"
+
+	"golang.org/x/pkgsite/internal/api/testdata"
+)
+
+func Example() {
+	fmt.Println("Package example")
+	// Output:
+	// Package example
+}
+
+func ExampleF() {
+	pkg.F()
+	fmt.Println("F example")
+	// Output:
+	// F example
+}
+
+func ExampleF_second() {
+	pkg.F()
+	fmt.Println("F second example")
+	// Output:
+	// F second example
+}
+
+func ExampleT() {
+	_ = pkg.T(0)
+	fmt.Println("T example")
+	// Output:
+	// T example
+}
+
+func ExampleT_M() {
+	var t pkg.T
+	t.M()
+	fmt.Println("M example")
+	// Output:
+	// M example
+}
diff --git a/internal/api/testdata/text-examples.golden b/internal/api/testdata/text-examples.golden
new file mode 100644
index 00000000..c8c10435
--- /dev/null
+++ b/internal/api/testdata/text-examples.golden
@@ -0,0 +1,122 @@
+package pkg
+
+Package pkg has every form of declaration.
+
+# Heading
+
+Search Google for details.
+
+# Links
+
+  - pkgsite repo, https://go.googlesource.com/pkgsite
+  - Play with Go, https://play-with-go.dev
+
+[Google]: https://google.com
+
+Example:
+	{
+		fmt.Println("Package example")
+	}
+
+	Output:
+	Package example
+
+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.
+
+Example:
+	{
+		pkg.F()
+		fmt.Println("F example")
+	}
+
+	Output:
+	F example
+
+Example (second):
+	{
+		pkg.F()
+		fmt.Println("F second example")
+	}
+
+	Output:
+	F second example
+
+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.
+
+Example:
+	{
+		_ = pkg.T(0)
+		fmt.Println("T example")
+	}
+
+	Output:
+	T example
+
+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.
+
+Example:
+	{
+		var t pkg.T
+		t.M()
+		fmt.Println("M example")
+	}
+
+	Output:
+	M example