docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:07:39 +01:00
parent cd55a3980d
commit a2551d83d7
6 changed files with 257 additions and 86 deletions

View File

@@ -32,25 +32,43 @@ Use cases:
## Usage
A plugin registers itself when its package is imported:
A plugin registers itself when its package is imported. The plugin type implements `party.Plugin`:
```go
package blog
```go src=modules/party/example_plugin_test.go#BlogPlugin
// BlogPlugin is the acme.blog plugin: the Go form of a WinterCMS Plugin.php.
// A real plugin package also registers it from init with
// party.Register(&BlogPlugin{}).
type BlogPlugin struct{}
```
import (
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/party"
)
```go src=modules/party/example_plugin_test.go#BlogPlugin.ID
// ID is the plugin identifier in vendor.plugin form.
func (p *BlogPlugin) ID() string { return "acme.blog" }
```
type Plugin struct{}
```go src=modules/party/example_plugin_test.go#BlogPlugin.Requires
// Requires lists the plugins that must register and boot first ($require).
func (p *BlogPlugin) Requires() []string { return []string{"acme.user"} }
```
func (p *Plugin) ID() string { return "acme.blog" }
func (p *Plugin) Requires() []string { return []string{"acme.user"} }
func (p *Plugin) Register(app *backpack.App) error { return nil }
func (p *Plugin) Boot(app *backpack.App) error { return nil }
```go src=modules/party/example_plugin_test.go#BlogPlugin.Register
// Register runs before any plugin boots: publish services here.
func (p *BlogPlugin) Register(app *backpack.App) error { return nil }
```
func init() {
party.Register(&Plugin{})
```go src=modules/party/example_plugin_test.go#BlogPlugin.Boot
// Boot runs after every plugin registered: listen to events and look up
// services other plugins published.
func (p *BlogPlugin) Boot(app *backpack.App) error { return nil }
```
and the package's `init` function registers it:
```go src=modules/party/example_test.go#registerBlog
// registerBlog is the blog plugin package's init function: a real package
// names it init, so importing the package registers the plugin.
func registerBlog() {
party.Register(&BlogPlugin{})
}
```
@@ -60,10 +78,10 @@ Each application gets its own plugin instances: `party.Activate` gives every app
The application publishes its build-time metadata and activates the plugins it lists, in dependency order (`summer build` generates both lists):
```go
cfg, err := compass.Load("config")
```go src=modules/party/example_test.go#activate
cfg, err := compass.Load(dir)
if err != nil {
return err
return nil, nil, err
}
app := backpack.New(cfg)
info := []party.Info{
@@ -71,11 +89,11 @@ info := []party.Info{
{ID: "acme.blog", Version: "v0.2.5", Source: party.SourceModule},
}
if err := party.Describe(app, info, "v0.6.0"); err != nil {
return err
return nil, nil, err
}
plugins, err := party.Activate(app, []string{"acme.user", "acme.blog"})
if err != nil {
return err
return nil, nil, err
}
```