docs(flare,kiosk,lagoon): compile README Go examples via src= (quick-261118-qsd)

- flare: send region run by TestDocsNotifyReply against a loopback TLS push
  service; blogSubscriptions and the publish-source region run by
  TestDocsSubscriptionSource on a Postgres container (skips under -short)
- kiosk: write, newest and client regions run by TestDocsWriteManifest (a
  copy of the literal fixture), ExampleVersionsResponse and
  TestDocsBlogReleases (httptest registry); the CheckT fence reuses
  TestPluginManifest
- lagoon: new open region run by TestDocsOpenFromApp (DocsDSN added to
  export_docs_test.go); the model, create-post, on-database, publish and
  migrations fences reuse the Database pages' targets
This commit is contained in:
Jakub Zych
2026-11-18 19:53:27 +01:00
parent d04454c57b
commit c517db564c
7 changed files with 535 additions and 63 deletions

View File

@@ -26,8 +26,10 @@ WinterCMS keeps this data in a plugin's `Plugin.php` `pluginDetails()` and in `c
## Usage
```go
path, warnings, err := kiosk.Write(ctx, "plugins/acme/blog", kiosk.DeriveOptions{})
Regenerating the manifest of a plugin directory (plugins/acme/blog, say) and checking it:
```go src=modules/kiosk/example_test.go#write
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
if err != nil {
return err
}
@@ -36,7 +38,7 @@ for _, w := range warnings {
}
fmt.Println("wrote", path)
if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
if err := kiosk.Check(ctx, dir); err != nil {
var stale *kiosk.StaleError
if errors.As(err, &stale) {
fmt.Printf("expected:\n%s", stale.Want)
@@ -47,7 +49,7 @@ if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
Picking the newest release of a plugin that an application on framework v0.6.2 can install:
```go
```go src=modules/kiosk/example_test.go#newest
var versions kiosk.VersionsResponse
if err := json.Unmarshal(body, &versions); err != nil {
return err
@@ -61,25 +63,28 @@ fmt.Println("go get", v.Module+"@"+v.Version)
Asking the configured registry for a plugin's releases:
```go
```go src=modules/kiosk/example_test.go#client
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
if errors.Is(err, kiosk.ErrRegistryDisabled) {
return nil // plugins.registry_url is empty: no registry calls
return nil, nil // plugins.registry_url is empty: no registry calls
}
if err != nil {
return err
return nil, err
}
versions, err := client.Versions(ctx, "acme.blog")
if errors.Is(err, kiosk.ErrNotFound) {
return fmt.Errorf("acme.blog is not listed")
return nil, fmt.Errorf("acme.blog is not listed")
}
```
A plugin repository keeps its manifest current with one test:
```go
```go src=modules/kiosk/checkt_test.go#TestPluginManifest
// TestPluginManifest is the test a plugin repository adds next to its
// plugin.go, with "." as the directory. Here it guards the committed
// manifest of the literal fixture.
func TestPluginManifest(t *testing.T) {
kiosk.CheckT(t, ".")
kiosk.CheckT(t, "testdata/literal")
}
```