feat(11.1-04): add the Database section and the core Services pages

- docs/database: models, migrations, queries and pagination, relations,
  casts and validation, attachments and transactions (lagoon.Transaction,
  lagoon.AfterCommit, nested savepoints, lagoon.OnDatabase)
- docs/services: configuration, events, routing with auth groups, rate
  limiting, authentication, the OAuth server, mail and localization
- runnable Examples for lagoon, attach, compass, surf, wire, bouncer,
  wristband, postcard, phrasebook and festival; lagoon TestDocs* regions
  run on the package's Postgres harness through DocsDB
- 15 new required pages

modules/compass/example_test.go

@@ -0,0 +1,95 @@
+package compass_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing/fstest"
+
+	"git.golem15.com/golem15/summercms/modules/compass"
+)
+
+// writeConfig lays out a config directory: base sections and a development
+// override of one of them.
+func writeConfig(dir string) error {
+	files := map[string]string{
+		"app.yaml":                 "name: Acme\ndebug: false\n",
+		"mail.yaml":                "driver: log\nfrom: blog@example.com\n",
+		"env/development/app.yaml": "debug: true\n",
+	}
+	for name, body := range files {
+		path := filepath.Join(dir, filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return err
+		}
+		if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+type mailSettings struct {
+	Driver string `koanf:"driver"`
+	From   string `koanf:"from"`
+}
+
+func ExampleOpen() {
+	dir, err := os.MkdirTemp("", "acme-config")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(dir)
+	if err := writeConfig(dir); err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Environ stands in for the process environment (nil reads os.Environ).
+	cfg, err := compass.Open(compass.Options{
+		Dir:     dir,
+		Env:     "development",
+		Environ: []string{"SUMMER_MAIL__DRIVER=smtp"},
+	})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// A plugin's embedded config/config.yaml becomes its defaults.
+	plugin := fstest.MapFS{"config/config.yaml": {Data: []byte("posts_per_page: 10\n")}}
+	if err := cfg.MergePlugin("acme.blog", plugin); err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	fmt.Println(cfg.String("app.name"), cfg.Bool("app.debug"), cfg.Int("acme.blog.posts_per_page"))
+	var mail mailSettings
+	if err := cfg.LoadSection("mail", &mail); err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(mail.Driver, mail.From)
+	_, found := cfg.Lookup("app.timezone")
+	fmt.Println(cfg.Environment(), found)
+
+	// A runtime override, saved to env/development/overrides.yaml.
+	if err := cfg.Set("acme.blog.posts_per_page", 25); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := cfg.Persist(); err != nil {
+		fmt.Println(err)
+		return
+	}
+	saved, _ := os.ReadFile(filepath.Join(dir, "env", "development", "overrides.yaml"))
+	fmt.Print(string(saved))
+	// Output:
+	// Acme true 10
+	// smtp blog@example.com
+	// development false
+	// acme:
+	//     blog:
+	//         posts_per_page: 25
+}