docs(lighthouse,postcard,signpost): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:13:14 +01:00
parent a2551d83d7
commit 1e56d750ef
7 changed files with 482 additions and 150 deletions

View File

@@ -48,18 +48,9 @@ Hi **{{ .name }}**, thanks for joining the blog.
and sends it through the mailer the runtime published:
```go
package blog
import (
"context"
"errors"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/postcard"
)
func SendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
```go src=modules/postcard/example_test.go#sendWelcome
// sendWelcome sends the welcome mail through the mailer published at boot.
func sendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
mailer, ok := app.Lookup[postcard.Mailer]()
if !ok {
return errors.New("mailer not published")
@@ -74,17 +65,7 @@ func SendWelcome(ctx context.Context, app *backpack.App, email, name string) err
In tests, build the catalog and mailer directly and inspect what was sent:
```go
package blog
import (
"context"
"testing"
"testing/fstest"
"git.golem15.com/golem15/summercms/modules/postcard"
)
```go src=modules/postcard/example_test.go#TestWelcomeMail
func TestWelcomeMail(t *testing.T) {
mailFS := fstest.MapFS{"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome, {{ .name }}\"\n==\nHi **{{ .name }}**.\n")}}
cat := postcard.NewCatalog()
@@ -123,30 +104,14 @@ NOTE: {{ .text }}
<div class="note">{{ .text }}</div>
```
and declares it next to its templates:
and declares it next to its templates (`mailFS` is the plugin's `views/mail` directory, embedded with `//go:embed views/mail`; the plugin asserts `var _ pact.HasMailPartials = BlogPlugin{}`):
```go
package blog
```go src=modules/postcard/example_test.go#BlogPlugin.MailPartialsFS
func (BlogPlugin) MailPartialsFS() fs.FS { return mailFS }
```
import (
"embed"
"io/fs"
"git.golem15.com/golem15/summercms/modules/pact"
)
//go:embed views/mail
var mailFS embed.FS
type Plugin struct{}
var _ pact.HasMailPartials = Plugin{}
func (Plugin) ID() string { return "acme.blog" }
func (Plugin) MailPartialsFS() fs.FS { return mailFS }
func (Plugin) MailPartials() []string {
```go src=modules/postcard/example_test.go#BlogPlugin.MailPartials
func (BlogPlugin) MailPartials() []string {
return []string{"acme.blog::mail.partials.note"}
}
```
@@ -236,18 +201,12 @@ An override never stops mail:
`postcard.NewMailer` takes a source through `postcard.Options.Overrides`; any `postcard.OverrideSource` works, which is how a test supplies overrides without a database:
```go
package blog
import (
"context"
"git.golem15.com/golem15/summercms/modules/postcard"
)
```go src=modules/postcard/example_test.go#fixedOverrides
// fixedOverrides overrides one template with a fixed subject and body.
type fixedOverrides struct{}
```
```go src=modules/postcard/example_test.go#fixedOverrides.MailOverrides
func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcard.Overrides, error) {
if template != "acme.blog::mail.welcome" {
return postcard.Overrides{}, nil
@@ -257,7 +216,9 @@ func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcar
Body: "Good to see you, **{{ .name }}**.",
}}, nil
}
```
```go src=modules/postcard/example_test.go#newTestMailer
func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Mailer {
return postcard.NewMailer(cat, driver, postcard.Options{Overrides: fixedOverrides{}})
}
@@ -324,17 +285,7 @@ Sample values are strings and are used only by `postcard.Editor`; `Send` never r
`postcard.EditorFrom` returns the `postcard.Editor` of the mailer `postcard.Activate` published. Admin code describes unsaved content as a `postcard.Draft` and asks the editor to check, render or send it:
```go
package blog
import (
"context"
"errors"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/postcard"
)
```go src=modules/postcard/example_test.go#previewWelcome
// previewWelcome renders an edited welcome mail without saving it.
func previewWelcome(ctx context.Context, app *backpack.App, subject, body string) (postcard.Preview, error) {
editor, ok := postcard.EditorFrom(app)