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>

1 files changed, 122 insertions, 0 deletions

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