doc: generated testable examples with link to pkg.go.dev

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

assert/assert_examples_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/go-openapi/testify/codegen/v2/internal/generator/domains"
 	"github.com/go-openapi/testify/codegen/v2/internal/generator/funcmaps"
 	"github.com/go-openapi/testify/codegen/v2/internal/model"
+	exparser "github.com/go-openapi/testify/codegen/v2/internal/scanner/examples-parser"
 )
 
 const (
@@ -53,8 +54,11 @@ func (d *DocGenerator) Generate(opts ...GenerateOption) error {
 		return err
 	}
 
-	// Proposal for enhancement: other fun stuff
-	// - capture testable examples and render their source code
+	// capture testable examples from generated packages and attach them to
+	// the model so templates may render their source code.
+	if err := d.populateExamples(); err != nil {
+		return err
+	}
 
 	// reorganize accumulated package-based docs into domain-based docs
 	//
@@ -223,6 +227,93 @@ func (d *DocGenerator) loadTemplates() error {
 	return nil
 }
 
+// populateExamples runs the examples-parser against all generated packages in the
+// merged Documentation and attaches the discovered testable examples to the
+// corresponding Function and Ident objects.
+//
+// This must run before [reorganizeByDomain] because domain discovery copies
+// functions and types into domain entries.
+func (d *DocGenerator) populateExamples() error {
+	if !d.ctx.runnableExamples {
+		return nil
+	}
+
+	docs := domains.FlattenDocumentation(d.doc)
+
+	// derive the module root from the assertions import that every generated
+	// package carries (e.g. "github.com/go-openapi/testify/v2").
+	var rootPkg string
+	for _, doc := range docs {
+		if doc.Package != nil && doc.Package.Imports != nil {
+			if assertionsPath, ok := doc.Package.Imports[assertions]; ok {
+				rootPkg = path.Dir(path.Dir(assertionsPath))
+
+				break
+			}
+		}
+	}
+	if rootPkg == "" {
+		return nil // nothing to do
+	}
+
+	workDir, err := filepath.Abs(d.ctx.targetRoot)
+	if err != nil {
+		return fmt.Errorf("resolving target root: %w", err)
+	}
+
+	for _, doc := range docs {
+		pkg := doc.Package
+		if pkg == nil {
+			continue
+		}
+
+		// Skip the internal assertions package: testable examples live in the
+		// generated packages (assert, require), not in the source package.
+		if path.Base(pkg.Package) == assertions {
+			continue
+		}
+
+		importPath := rootPkg + "/" + pkg.Package
+		examples, parseErr := exparser.New(importPath, exparser.WithWorkDir(workDir)).Parse()
+		if parseErr != nil {
+			return fmt.Errorf("parsing examples for %s: %w", pkg.Package, parseErr)
+		}
+
+		populateFunctionExamples(pkg, examples)
+		populateIdentExamples(pkg.Types, examples)
+	}
+
+	return nil
+}
+
+func populateFunctionExamples(pkg *model.AssertionPackage, examples exparser.Examples) {
+	for i, fn := range pkg.Functions {
+		exs, ok := examples[fn.Name]
+		if !ok {
+			continue
+		}
+		renderables := make([]model.Renderable, len(exs))
+		for j := range exs {
+			renderables[j] = exs[j]
+		}
+		pkg.Functions[i].Examples = renderables
+	}
+}
+
+func populateIdentExamples(idents []model.Ident, examples exparser.Examples) {
+	for i, id := range idents {
+		exs, ok := examples[id.Name]
+		if !ok {
+			continue
+		}
+		renderables := make([]model.Renderable, len(exs))
+		for j := range exs {
+			renderables[j] = exs[j]
+		}
+		idents[i].Examples = renderables
+	}
+}
+
 func (d *DocGenerator) render(name string, target string, data any) error {
 	return renderTemplate(
 		d.ctx.index,

assert/assert_forward.go

@@ -7,6 +7,8 @@ import (
 	"fmt"
 	"regexp"
 	"strings"
+
+	"github.com/go-openapi/testify/codegen/v2/internal/model"
 )
 
 var (
@@ -24,7 +26,18 @@ const sensiblePrealloc = 20
 //
 //  1. Reference-style markdown links: [text]: url
 //  2. Godoc-style links: [errors.Is], [testing.T], etc.
-func FormatMarkdown(in string) string {
+//
+//nolint:gocognit,gocyclo,cyclop // will refactor later this highly complex function
+func FormatMarkdown(in string, object any) string {
+	var (
+		testableExamples []model.Renderable
+		funcName         string
+	)
+	if function, ok := (object).(model.Function); ok {
+		testableExamples = function.Examples
+		funcName = function.Name
+	}
+
 	// Step 1: Extract reference-style link definitions
 	// Pattern: [text]: url (at start of line or after whitespace)
 	refLinks := make(map[string]string)
@@ -112,6 +125,7 @@ func FormatMarkdown(in string) string {
 	tabsCollection := false
 	expanded := false
 	tab := false
+	hasTestableExamples := false
 
 	for line := range strings.SplitSeq(processed, "\n") {
 		if expanded && len(strings.TrimSpace(line)) == 0 {
@@ -147,12 +161,16 @@ func FormatMarkdown(in string) string {
 			tabsCollection = true
 		}
 
+		if strings.EqualFold(section, "Examples") && len(testableExamples) > 0 {
+			hasTestableExamples = true
+			continue // skip : we'll add testable examples below
+		}
+
 		title := titleize(section)
 		if tab {
 			trailer = append(trailer, "```")
 			trailer = append(trailer, `{{< /tab >}}`)
 		}
-
 		trailer = append(trailer, fmt.Sprintf(`{{%% tab title="%s" %%}}`, title))
 		trailer = append(trailer, "```go")
 		tab = true
@@ -163,6 +181,28 @@ func FormatMarkdown(in string) string {
 		trailer = append(trailer, `{{< /tab >}}`)
 	}
 
+	if hasTestableExamples {
+		trailer = append(trailer, `{{% tab title="Testable Examples" %}}`)
+		trailer = append(trailer, `{{% cards %}}`)
+		tabsCollection = true
+
+		for _, example := range testableExamples {
+			trailer = append(trailer, `{{% card href="https://go.dev/play/" %}}`)
+			trailer = append(trailer, "\n")
+			trailer = append(trailer, `*Copy and click to open Go Playground*`)
+			trailer = append(trailer, "\n")
+			trailer = append(trailer, "```go")
+			trailer = append(trailer, fmt.Sprintf("// real-world test would inject *testing.T from Test%s(t *testing.T)", funcName))
+			trailer = append(trailer, example.Render())
+			trailer = append(trailer, "```")
+			trailer = append(trailer, `{{% /card %}}`)
+			trailer = append(trailer, "\n")
+		}
+		trailer = append(trailer, `{{% /cards %}}`)
+		trailer = append(trailer, `{{< /tab >}}`)
+		trailer = append(trailer, "\n")
+	}
+
 	if tabsCollection {
 		trailer = append(trailer, `{{< /tabs >}}`)
 		trailer = append(trailer, `{{% /expand %}}`)

codegen/internal/generator/doc_generator.go

@@ -13,7 +13,7 @@ import (
 func TestMarkdownFormatEnhanced(t *testing.T) {
 	for tt := range markdownTestCases() {
 		t.Run(tt.name, func(t *testing.T) {
-			result := FormatMarkdown(tt.input)
+			result := FormatMarkdown(tt.input, nil)
 
 			for _, want := range tt.contains {
 				if !strings.Contains(result, want) {
@@ -47,7 +47,7 @@ Values can be of type [strings.Builder] or [Boolean].
 	failure: "not empty"
 [Zero values]: https://go.dev/ref/spec#The_zero_value`
 
-	result := FormatMarkdown(input)
+	result := FormatMarkdown(input, nil)
 	t.Logf("Output:\n%s", result)
 }
 

codegen/internal/generator/funcmaps/markdown.go

@@ -268,7 +268,7 @@ func (g *Generator) transformModel() error {
 	tgt.EnableForward = g.ctx.enableForward
 	tgt.EnableGenerics = g.ctx.enableGenerics
 	tgt.EnableExamples = g.ctx.generateExamples
-	tgt.RunnableExamples = g.ctx.runnableExamples
+	tgt.RunnableExamples = g.ctx.runnableExamples /// instructs the doc generator to scan the generated packages to collect runnable examples
 	if tgt.Imports == nil {
 		tgt.Imports = make(model.ImportMap, 1)
 	}

codegen/internal/generator/funcmaps/markdown_test.go

@@ -32,7 +32,7 @@ func Example{{ .Name }}() {
         {{- range .Tests }}
           {{- if eq .ExpectedOutcome 1 }}{{/* TestSuccess */}}
             {{- if (not $first) }}{{ println "" }}{{- end }}{{ $first = false }}
-    t := new(testing.T)
+    t := new(testing.T) // should come from testing, e.g. func Test{{ $fn.Name }}(t *testing.T)
             {{- if $isRequire }}
     {{ $pkg }}.{{ $fn.Name }}{{ if hasSuffix $fn.Name "OfTypeT" }}[myType]{{ end }}(t, {{ relocate .TestedValues $pkg }})
     fmt.Println("passed")

codegen/internal/generator/generator.go

@@ -27,6 +27,10 @@ func New(t T) *{{ .Receiver }} {
   }
 }
 
+func (a *{{ $.Receiver }}) T() T {
+	return a.t
+}
+
 {{- range .Functions }} 
   {{- if and (not .IsGeneric) (not .IsHelper) (not .IsConstructor) }}{{/* generics can't be added to the receiver */}}
 

codegen/internal/generator/templates/assertion_examples_test.gotmpl

@@ -60,7 +60,7 @@ Generic assertions are marked with a {{ print "{{" }}% icon icon="star" color=or
 <div style="background-color: #fceea5;">{{/* like godoc TODO: use css */}}
         {{- end }}
 
-{{ mdformat .DocString }}{{/* reformat inner markdown and reformat */}}
+{{ mdformat .DocString . }}{{/* reformat inner markdown and reformat */}}
 
         {{- $funcName := .Name }}
         {{- with $extraPackages }}
@@ -133,7 +133,7 @@ Generic assertions are marked with a {{ print "{{" }}% icon icon="star" color=or
 <div style="background-color: #fceea5;">{{/* like godoc */}}
         {{- end }}
 
-{{ mdformat .DocString }}
+{{ mdformat .DocString . }}
 
         {{- $funcName := .Name }}
         {{- with $extraPackages }}

codegen/internal/generator/templates/assertion_forward.gotmpl

@@ -27,6 +27,10 @@ func New(t T) *{{ .Receiver }} {
   }
 }
 
+func (a *{{ $.Receiver }}) T() T {
+	return a.t
+}
+
 {{- range .Functions }} 
   {{- if and (not .IsGeneric) (not .IsHelper) (not .IsConstructor) }}{{/* generics can't be added to the receiver */}}