docs: Add examples of building and publishing images (#108)

Motivation
----------

As with authentication configuration, it is useful for new users to be
able to refer to concrete examples showing how to use the plugin.

Modifications
-------------

* Add a section to the 'run' document showing how to build and run an
image in one command.
* Add sections showing how to publish images to some popular public
container registries.

Result
------

Users can refer to examples showing how to use the plugin to build and
run images.

Test Plan
---------

Steps tested manually.
All automated tests continue to pass.

---------

Co-authored-by: Joseph Heck <[email protected]>

Author: euanh

Package.swift

@@ -78,9 +78,7 @@ let package = Package(
             ),
             dependencies: [.target(name: "containertool")]
         ),
-        // Empty target that builds the DocC catalog at /SwiftContainerPluginDocumentation/Documentation.docc.
-        // The ContainerImageBuilder catalog includes high-level, user-facing documentation about using
-        // the ContainerImageBuilder plugin from the command-line.
+        // Empty target which builds high-level, user-facing documentation about using the plugin from the command-line.
         .target(
             name: "swift-container-plugin",
             exclude: ["README.md"]

Sources/containertool/Documentation.docc/containertool.md

@@ -13,7 +13,7 @@ Wrap a binary in a container image and publish it.
 `containertool` can be run directly but its main role is to be a helper tool used by the `ContainerImageBuilder` command plugin.   See the plugin documentation for examples of how to use it in this way.
 
 ```text
-OVERVIEW: Build and upload a container image
+OVERVIEW: Build and publish a container image
 
 USAGE: containertool --repository <repository> <executable> [--username <username>] [--password <password>] [--verbose] [--allow-insecure-http <allow-insecure-http>] [--architecture <architecture>] --from <from> [--os <os>] [--tag <tag>]
 

Sources/containertool/containertool.swift

@@ -25,7 +25,7 @@ enum AllowHTTP: String, ExpressibleByArgument, CaseIterable { case source, desti
 @main struct ContainerTool: AsyncParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "containertool",
-        abstract: "Build and upload a container image"
+        abstract: "Build and publish a container image"
     )
 
     @Option(help: "Default registry for references which do not specify a registry")

Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md

@@ -14,7 +14,7 @@ Swift Container Plugin is distributed as a Swift Package Manager package.    To
 Recent versions of `swift package` support the `add-dependency` command:
 
 ```shell
-swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.5.0
+swift package add-dependency https://github.com/apple/swift-container-plugin --from 1.0.0
 ```
 
 ### Install the plugin by manually editing `Package.swift`
@@ -23,7 +23,7 @@ If you cannot use the `swift package add-dependency` comand, append the followin
 
 ```swift
 package.dependencies += [
-    .package(url: "https://github.com/apple/swift-container-plugin", from: "0.5.0"),
+    .package(url: "https://github.com/apple/swift-container-plugin", from: "1.0.0"),
 ]
 ```
 

Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md

@@ -29,7 +29,7 @@ To use the plugin:
 ### Build and publish a container image
 
 After adding the plugin to your project, you can build and publish a container image in one step.
-Here is how to build the [HelloWorld example](https://github.com/apple/swift-container-plugin/tree/main/Examples/HelloWorldHummingbird) as a static binary for Linux running the `x86_64` architecture:
+Here is how to build the [HelloWorld example](https://github.com/apple/swift-container-plugin/tree/main/Examples/HelloWorldHummingbird) as a static executable for Linux running the `x86_64` architecture:
 
 ```
 % swift package --swift-sdk x86_64-swift-linux-musl \

Sources/swift-container-plugin/Documentation.docc/build.md

@@ -1,19 +1,19 @@
 # Build and package your service
 
-Build a container image and upload it to a registry.
+Build a container image and publish it to a registry.
 
 ## Overview
 
-The plugin exposes the command `build-container-image` which you invoke to build your service, package it in a container image and upload it to a container registry, in a single command:
+The plugin exposes the command `build-container-image` which you invoke to build your service, package it in a container image and publish it to a container registry, in a single command:
 
 ```shell
 % swift package --swift-sdk x86_64-swift-linux-musl \
         build-container-image --from swift:slim --repository registry.example.com/myservice
 ```
 
-* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable.   In this case we are using the Static Linux SDK, installed earlier, to build an statically-linked x86_64 Linux binary.
+* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable.   In this case we are using the Static Linux SDK, [installed earlier](<doc:requirements>), to build an statically-linked x86_64 Linux executable.
 * The `--from` argument specifies the base image on which our service will run.   `swift:slim` is the default, but you can choose your own base image or use `scratch` if your service does not require a base image at all.
-* The `--repository` argument specifies the repository to which the plugin will upload the finished image.
+* The `--repository` argument specifies the repository to which the plugin will publish the finished image.
 
 > Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry.
 >
@@ -43,3 +43,45 @@ registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed919
 
 When the plugin finishes, it prints a reference identifying the new image.
 Any standard container runtime can use the reference to pull and run your service.
+
+### Default registry
+
+If you don't include a registry name in the `--repository` argument, the plugin will publish your image to Docker Hub by default.
+
+You can override the default registry by using the `--default-registry` argument or setting the `CONTAINERTOOL_DEFAULT_REGISTRY` environment variable.
+
+The following examples show how to publish images to some popular registry providers.
+
+### Docker Hub
+
+The following example publishes an image to a repository named `mydockerid/example` on Docker Hub.
+
+The repository will be created if it does not already exist.
+
+```
+swift package --swift-sdk x86_64-swift-linux-musl build-container-image \
+    --repository mydockerid/example
+```
+
+### GitHub Container Registry
+
+The following example publishes an image to a repository named `mydockerid/example` on GitHub Container Registry.
+
+The repository will be created if it does not already exist.
+
+```
+swift package --swift-sdk x86_64-swift-linux-musl build-container-image \
+    --repository ghcr.io/mygithubusername/example
+```
+
+### Amazon Elastic Container Registry
+
+The following example publishes an image to the repository named `example/test` on Amazon Elastic Container Registry.
+
+**The repository must already exist before you push to it.**
+Create a repository using the [Amazon ECR Console](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html).
+
+```
+swift package --swift-sdk x86_64-swift-linux-musl build-container-image \
+    --repository 123456789012.dkr.ecr.us-west-2.amazonaws.com/example/test
+```

Sources/swift-container-plugin/Documentation.docc/run.md

@@ -18,4 +18,20 @@ When the service has started, we can access it with a web browser or `curl`:
 ```
 % curl localhost:8080
 Hello World, from Hummingbird on Ubuntu 24.04.2 LTS
-```
+```
+
+### Build and run in one step
+
+Swift Container Plugin prints a reference to the newly built image on standard output.
+You can pipe the image reference to a deployment command or pass it as an argument using shell command substitution.
+
+This allows you to build and deploy a container image in one shell command, using a convenient pattern offered by tools such as [ko.build](https://ko.build):
+
+```
+% podman run -p 8080:8080 \
+    $(swift package --swift-sdk x86_64-linux-swift-musl \
+        build-container-image --repository registry.example.com/myservice)
+Trying to pull registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df...
+...
+2024-05-26T22:57:50+0000 info HummingBird : [HummingbirdCore] Server started and listening on 0.0.0.0:8080
+```

Sources/swift-container-plugin/README.md

@@ -1,7 +1,6 @@
-# ContainerImageBuilder Plugin Documentation
+# Swift Container Plugin User Documentation
 
-`ContainerImageBuilderPluginDocumentation` is an otherwise empty target that includes high-level,
-user-facing documentation about using the ContainerImageBuilder plugin from the command-line.
+This is an otherwise empty target that includes high-level, user-facing documentation about using the plugin from the command-line.
 
 To preview the documentation, run the following command: