docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -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
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -2,7 +2,11 @@ package party_test
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"slices"
|
||||
"testing"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"git.golem15.com/golem15/summercms/modules/compass"
|
||||
"git.golem15.com/golem15/summercms/modules/party"
|
||||
)
|
||||
|
||||
@@ -11,3 +15,71 @@ func ExamplePlugin() {
|
||||
fmt.Println(p.ID())
|
||||
// Output: acme.blog
|
||||
}
|
||||
|
||||
// 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{})
|
||||
}
|
||||
|
||||
// userPlugin is the acme.user plugin BlogPlugin requires.
|
||||
type userPlugin struct{}
|
||||
|
||||
func (*userPlugin) ID() string { return "acme.user" }
|
||||
func (*userPlugin) Requires() []string { return nil }
|
||||
func (*userPlugin) Register(*backpack.App) error { return nil }
|
||||
func (*userPlugin) Boot(*backpack.App) error { return nil }
|
||||
|
||||
// startApp is the part of an application's generated main that loads the
|
||||
// configuration in dir and activates the plugins.
|
||||
func startApp(dir string) (*backpack.App, []party.Plugin, error) {
|
||||
// docs:start activate
|
||||
cfg, err := compass.Load(dir)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
app := backpack.New(cfg)
|
||||
info := []party.Info{
|
||||
{ID: "acme.user", Source: party.SourceLocal},
|
||||
{ID: "acme.blog", Version: "v0.2.5", Source: party.SourceModule},
|
||||
}
|
||||
if err := party.Describe(app, info, "v0.6.0"); err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
plugins, err := party.Activate(app, []string{"acme.user", "acme.blog"})
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
// docs:end activate
|
||||
return app, plugins, nil
|
||||
}
|
||||
|
||||
// TestDocsActivate registers both plugins, starts an application on an
|
||||
// empty config directory and checks the activation order, the published
|
||||
// metadata and the plugin methods the README shows.
|
||||
func TestDocsActivate(t *testing.T) {
|
||||
party.DocsRegistry(t)
|
||||
registerBlog()
|
||||
party.Register(&userPlugin{})
|
||||
|
||||
app, plugins, err := startApp(t.TempDir())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var ids []string
|
||||
for _, p := range plugins {
|
||||
ids = append(ids, p.ID())
|
||||
}
|
||||
if want := []string{"acme.user", "acme.blog"}; !slices.Equal(ids, want) {
|
||||
t.Fatalf("activated %v, want %v", ids, want)
|
||||
}
|
||||
installed, ok := app.Lookup[party.Installed]()
|
||||
if !ok || installed.Framework != "v0.6.0" {
|
||||
t.Fatalf("Installed = %+v, %v", installed, ok)
|
||||
}
|
||||
|
||||
p := plugins[1]
|
||||
if !slices.Equal(p.Requires(), []string{"acme.user"}) || p.Register(app) != nil || p.Boot(app) != nil {
|
||||
t.Fatalf("BlogPlugin methods: %v", p.Requires())
|
||||
}
|
||||
}
|
||||
|
||||
11
modules/party/export_docs_test.go
Normal file
11
modules/party/export_docs_test.go
Normal file
@@ -0,0 +1,11 @@
|
||||
package party
|
||||
|
||||
import "testing"
|
||||
|
||||
// DocsRegistry swaps the process-wide plugin registry for an empty one for
|
||||
// the length of the test, for the docs examples in example_test.go that
|
||||
// register plugins.
|
||||
func DocsRegistry(t *testing.T) {
|
||||
t.Helper()
|
||||
withRegistry(t)
|
||||
}
|
||||
Reference in New Issue
Block a user