docker/compose
1
0
Fork 0
mirror of https://github.com/docker/compose.git synced 2026-10-12 02:13:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(sdk): document the EventProcessor API that actually exists

Browse Source 
sdk.md advertised a 'progress' package (progress.NewTTYWriter,
NewPlainWriter, NewJSONWriter, NewQuietWriter) that does not exist in
the repository, and typed WithEventProcessor against it. Anyone
following the doc writes code that cannot compile — or recreates the
phantom package.

The section now points at the real surface: api.EventProcessor, the
silent-by-default behavior when no processor is configured, and the
CLI's actual renderers in cmd/display (Full, Plain, JSON, Quiet) with
their real signatures.

Part of #14074 (A: the code misdescribes its own structure).

Signed-off-by: Nicolas De Loof <[email protected]>
This commit is contained in:
Nicolas De Loof
2026-08-27 10:57:44 +02:00
committed by Guillaume Lours
parent 03ad3cc1c2
commit 7b63e4fa33
1 changed files with 11 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sdk.md
+11 -7
View File
@@ -107,7 +107,7 @@ options allow you to configure I/O streams, concurrency limits, dry-run mode, an
- `WithDryRun` - Run operations in dry-run mode without actually applying changes
- `WithContextInfo(api.ContextInfo)` - Set custom Docker context information
- `WithProxyConfig(map[string]string)` - Configure HTTP proxy settings for builds
- `WithEventProcessor(progress.EventProcessor)` - Receive progress events and operation notifications
- `WithEventProcessor(api.EventProcessor)` - Receive progress events and operation notifications
These options provide fine-grained control over the SDK's behavior, making it suitable for various integration
scenarios including CLI tools, web services, automation scripts, and testing environments.
@@ -145,13 +145,17 @@ Common status text values include: `Creating`, `Created`, `Starting`, `Started`,
### Built-in `EventProcessor` implementations
The SDK provides three ready-to-use `EventProcessor` implementations:
The `EventProcessor` interface is defined in `github.com/docker/compose/v5/pkg/api`. When no
`WithEventProcessor` option is passed, events are silently discarded.
- `progress.NewTTYWriter(io.Writer)` - Renders an interactive terminal UI with progress bars and task lists
(similar to the Docker Compose CLI output)
- `progress.NewPlainWriter(io.Writer)` - Outputs simple text-based progress messages suitable for non-interactive
The renderers used by the Docker Compose CLI live in the `github.com/docker/compose/v5/cmd/display`
package and can be reused:
- `display.Full(out, info io.Writer, detached bool)` - Renders the interactive terminal UI with progress bars
and task lists (the default Docker Compose CLI output)
- `display.Plain(out io.Writer)` - Outputs simple text-based progress messages suitable for non-interactive
environments or log files
- `progress.NewJSONWriter()` - Render events as JSON objects
- `progress.NewQuietWriter()` - (Default) Silently processes events without producing any output
- `display.JSON(out io.Writer)` - Renders each event as a JSON object
- `display.Quiet()` - Silently discards events (same behavior as the default)
Using `EventProcessor`, a custom UI can be plugged into `docker/compose`.