docs: Split ContainerBuildPlugin documentation into multiple pages (#99)

Motivation
----------

Most of the documentation explaining how a user should run the plugin is
in a single DoCC file under the `ContainerImageBuilderPlugin` target
(this otherwise empty target is needed because DoCC does not generate
documentation for plugins).

This documentation would be easier to read, and easier to expand with
more information, if it was split into several sections. This would
provide an outline view in the left-hand pane (the "curation") which
would allow users to jump directly to sections of interest, and make
internal links between documentation sections easier.

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

* Rename `ContainerImageBuilderPlugin` to `swift-container-plugin`.
`swift-container-plugin` will hold all the high level documentation,
examples and tutorials for the project. A future PR will add a manual
page which specifically covers only the plugin.
*
 
Result
------

The existing documentation is better structured. A number of small edits
have been made for clarity.

Test Plan
---------

* No functional change.   
* DoCC checks are already run by the `soundness` GitHub CI job and
continue to pass; all notes and usage warnings fixed.

---------

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

Author: euanh

.spi.yml

@@ -3,4 +3,4 @@ builder:
   configs:
     - documentation_targets:
         - containertool
-        - ContainerImageBuilderPlugin
+        - swift-container-plugin

Package.swift

@@ -27,7 +27,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0"..<"4.0.0"),
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
         .package(url: "https://github.com/apple/swift-http-types.git", from: "1.2.0"),
-        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+        .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         .target(
@@ -78,12 +78,11 @@ let package = Package(
             ),
             dependencies: [.target(name: "containertool")]
         ),
-        // Empty target that builds the DocC catalog at /ContainerImageBuilderPluginDocumentation/ContainerImageBuilder.docc.
+        // 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.
         .target(
-            name: "ContainerImageBuilderPlugin",
-            path: "Sources/ContainerImageBuilderPluginDocumentation",
+            name: "swift-container-plugin",
             exclude: ["README.md"]
         ),
         .testTarget(

README.md

@@ -17,7 +17,7 @@ Swift Container Plugin makes it easy to build container images for servers writt
 Find out more and see it in action:
 
 * [How to put Swift in a box](https://fosdem.org/2025/schedule/event/fosdem-2025-5116-how-to-put-swift-in-a-box-building-container-images-with-swift-container-plugin/) at [FOSDEM 2025](https://fosdem.org/2025/schedule/track/swift/).
-* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/speakers/euan-harris/).
+* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/2024/speakers/euan-harris/).
 
 ## Usage
 

Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md

@@ -8,7 +8,7 @@ Wrap a binary in a container image and publish it.
 
 > Note: A container image is the standard way to package cloud software.   Once you have wrapped your server in a container image, you can deploy it on any public or private cloud service based on [Kubernetes](https://kubernetes.io), or run it locally using a desktop container runtime.
 
-## Usage
+### Usage
 
 `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.
 
@@ -23,6 +23,7 @@ ARGUMENTS:
 OPTIONS:
   --repository <repository>
                           Repository path
+  --resources <resources> Resource bundle directory
   --username <username>   Username
   --password <password>   Password
   -v, --verbose           Verbose output
@@ -33,5 +34,10 @@ OPTIONS:
   --from <from>           Base image reference
   --os <os>               Operating system (default: linux)
   --tag <tag>             Tag for this manifest
+  --enable-netrc/--disable-netrc
+                          Load credentials from a netrc file (default:
+                          --enable-netrc)
+  --netrc-file <netrc-file>
+                          Specify the netrc file path
   -h, --help              Show help information.
 ```

Sources/containertool/Documentation.docc/containertool.md

@@ -0,0 +1,37 @@
+# Add the plugin to your project
+
+Make Swift Container Plugin available in your project.
+
+## Overview
+
+Swift Container Plugin is distributed as a Swift Package Manager package.    To make it available, you must add it as a dependency of your project.
+
+### Install the plugin using the `swift package` CLI
+
+> Adding the same dependency to your project more than once will prevent it from building.
+> If this happens, delete the duplicate dependency lines from `Package.swift` and rebuild.
+
+Recent versions of `swift package` suupport the `add-dependency` command:
+
+```shell
+swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.5.0
+```
+
+### Install the plugin by manually editing `Package.swift`
+
+If you cannot use the `swift package add-dependency` comand, append the following lines to your project's `Package.swift` file:
+
+```swift
+package.dependencies += [
+    .package(url: "https://github.com/apple/swift-container-plugin", from: "0.5.0"),
+]
+```
+
+### Check that the plugin is available
+
+After installation, Swift Package Manager should show that the `ContainerImageBuilder` is now available:
+
+```shell
+% swift package plugin --list
+‘build-container-image’ (plugin ‘ContainerImageBuilder’ in package ‘swift-container-plugin)
+```

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

@@ -11,10 +11,18 @@
 -->
 <plist version="1.0">
 <dict>
-    <key>CDDefaultCodeListingLanguage</key>
-    <string>shell</string>
-    <key>CDDefaultModuleKind</key>
-    <string>Command Plugin</string>
+    	<key>CDDefaultCodeListingLanguage</key>
+	<string>shell</string>
+	<key>CFBundleName</key>
+	<string>swift-container-plugin</string>
+	<key>CFBundleDisplayName</key>
+	<string>swift-container-plugin</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.apple.ContainerPlugin</string>
+	<key>CFBundlePackageType</key>
+	<string>DOCS</string>
+	<key>CDDefaultModuleKind</key>
+	<string>Tool</string>
 </dict>
 </plist>
 

Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/Info.plist renamed to Sources/swift-container-plugin/Documentation.docc/Info.plist

@@ -0,0 +1,79 @@
+# Swift Container Plugin
+
+@Metadata {
+    @TechnologyRoot()
+}
+
+Build and publish container images using Swift Package Manager.
+
+## Overview
+
+Container images are the standard way to package cloud software today.   Once you have packaged your server in a container image, you can deploy it on any container-based public or private cloud service, or run it locally using a desktop container runtime.
+
+Swift Container Plugin makes it easy to build container images for servers written in Swift, using Swift Package Manager.
+
+Find out more and see it in action:
+
+* [How to put Swift in a box](https://fosdem.org/2025/schedule/event/fosdem-2025-5116-how-to-put-swift-in-a-box-building-container-images-with-swift-container-plugin/) at [FOSDEM 2025](https://fosdem.org/2025/schedule/track/swift/).
+* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/2024/speakers/euan-harris/).
+
+### Usage
+
+Use the Swift Container Plugin to package an executable product from your Swift package into a container image and publish it to a container registry.
+
+To use the plugin:
+- <doc:Adding-the-plugin-to-your-project>
+- <doc:requirements>
+- <doc:authentication>
+
+### 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:
+
+```
+% swift package --swift-sdk x86_64-swift-linux-musl \
+        build-container-image --repository registry.example.com/myservice
+...
+Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports.
+Stated reason: “This command publishes images to container registries over the network”.
+Allow this plugin to allow all network connections on all ports? (yes/no) yes
+...
+Building for debugging...
+Build of product 'containertool' complete! (4.95s)
+...
+Build of product 'hello-world' complete! (5.51s)
+...
+[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42
+[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4
+[ContainerImageBuilder] Built application layer
+[ContainerImageBuilder] Uploading application layer
+[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists
+[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists
+[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists
+registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
+```
+
+### Run the image
+
+You can deploy your service in the cloud, or use a standards-compliant container runtime such as `podman` to run it locally:
+
+```
+% podman run -p 8080:8080 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
+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
+```
+
+Take a look at the [Examples](Examples).
+
+## Topics
+
+### Essentials
+- <doc:requirements>
+- <doc:Adding-the-plugin-to-your-project>
+- <doc:authentication>
+
+### Building and running
+- <doc:build>
+- <doc:run>

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

@@ -0,0 +1,17 @@
+# Set up your registry credentials
+
+Configure the plugin to authenticate to your container registry.
+
+## Overview
+
+Many container registries require authentication in order to push images, or even pull them.
+The plugin reads your registry credentials from a `.netrc` file in your home directory.
+Add a record into the `.netrc` file for each registry you use, the plugin uses the authentication by the registry you choose.
+
+The following example shows placeholder values for the registry `registry.example.com`:
+
+```
+machine registry.example.com
+  login myuser
+  password mypassword
+```

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

@@ -0,0 +1,45 @@
+# Build and package your service
+
+Build a container image and upload 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:
+
+```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 `--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.
+
+> Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry.
+>
+> ```
+> Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports.
+> Stated reason: “This command publishes images to container registries over the network”.
+> Allow this plugin to allow all network connections on all ports? (yes/no)
+> ```
+>
+> Type `yes` to continue.
+
+```
+Building for debugging...
+Build of product 'containertool' complete! (4.95s)
+...
+Build of product 'hello-world' complete! (5.51s)
+...
+[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42
+[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4
+[ContainerImageBuilder] Built application layer
+[ContainerImageBuilder] Uploading application layer
+[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists
+[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists
+[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists
+registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
+```
+
+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.