Migrates plugin documentation into DocC

Sources/PackageManagerDocs/Documentation.docc/Documentation.md

@@ -30,10 +30,11 @@ The Swift Package Manager lets you share your code as a package, depend on and u
 - <doc:BundlingResources>
 - <doc:ReleasingPublishingAPackage>
 - <doc:ContinuousIntegration>
-- <doc:UsingShellCompletion>
-- <doc:SwiftPMAsALibrary>
+- <doc:Plugins>
 - <doc:ModuleAliasing>
 - <doc:PackageCollections>
+- <doc:UsingShellCompletion>
+- <doc:SwiftPMAsALibrary>
 
 <!-- ### Command Plugins -->
 <!-- placeholder for content about swift package manager extensions - command plugins -->

Sources/PackageManagerDocs/Documentation.docc/Package/PackagePlugin.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.6")
 }
 
 

Sources/PackageManagerDocs/Documentation.docc/PackageCollections.md

@@ -1,5 +1,9 @@
 # Package Collections
 
+@Metadata {
+    @Available("Swift", introduced: "5.5")
+}
+
 Learn to create, publish and use Swift package collections.
 
 ## Overview
@@ -332,7 +336,7 @@ A signed package collection has an extra `signature` object:
 ```
 
 - The signature string (represented by `"<SIGNATURE>"`) is used to verify the contents of the collection file haven't been tampered with since it was signed when SwiftPM user [adds the collection](<doc:PackageCollectionAdd#Signed-package-collections>) to their configured list of collections. It includes the certificate's public key and chain.
-- `certificate` contains details extracted from the signing certificate. `subject.commonName` should be consistent with the name of the publisher so that it's recognizable by users. The root of the certificate must be [installed and trusted on users' machines](<doc:PackageCollectionAdd#trusted-root-certificates>).
+- `certificate` contains details extracted from the signing certificate. `subject.commonName` should be consistent with the name of the publisher so that it's recognizable by users. The root of the certificate must be [installed and trusted on users' machines](<doc:PackageCollectionAdd#Trusted-root-certificates>).
 
 ### Requirements on signing certificate
 
@@ -349,7 +353,8 @@ Non-expired, non-revoked Swift Package Collection certificates from [developer.a
 
 With the `package-collection-sign` tool, the root certificate provided as input for signing a collection is automatically trusted. When SwiftPM user tries to add the collection, however,
 the root certificate must either be preinstalled with the OS (Apple platforms only) or found in the `~/.swiftpm/config/trust-root-certs` directory (all platforms) or shipped with 
-the [certificate-pinning configuration](<doc:#Protecting-package-collections>), otherwise the [signature check](<doc:PackageCollectionAdd#Signed-package-collections>) will fail. Collection publishers should make the DER-encoded 
+the [certificate-pinning configuration](<doc:#Protecting-package-collections>), otherwise the [signature check](<doc:PackageCollectionAdd#Signed-package-collections>) will fail.
+Collection publishers should make the DER-encoded 
 root certificate(s) that they use downloadable so that users can adjust their setup if needed.
 
 

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionAdd.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 Add a new collection.

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionDescribe.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 Get metadata for a collection or a package included in an imported collection.

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionList.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 List configured collections.

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionRefresh.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 Refresh configured collections.

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionRemove.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 Remove a configured collection.

Sources/PackageManagerDocs/Documentation.docc/PackageCollections/PackageCollectionSearch.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.5")
 }
 
 Search for packages by keywords or module names.

Sources/PackageManagerDocs/Documentation.docc/PackageRegistry/PackageRegistryLogin.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.9")
 }
 
 Log in to a registry.

Sources/PackageManagerDocs/Documentation.docc/PackageRegistry/PackageRegistryLogout.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.9")
 }
 
 Log out from a registry

Sources/PackageManagerDocs/Documentation.docc/PackageRegistry/PackageRegistryPublish.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.9")
 }
 
 Publish to a registry.

Sources/PackageManagerDocs/Documentation.docc/PackageRegistry/PackageRegistrySet.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.9")
 }
 
 Set a custom registry.

Sources/PackageManagerDocs/Documentation.docc/PackageRegistry/PackageRegistryUnset.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @PageImage(purpose: icon, source: command-icon)
+    @Available("Swift", introduced: "5.9")
 }
 
 Remove a configured registry.

Sources/PackageManagerDocs/Documentation.docc/Plugins.md

@@ -0,0 +1,60 @@
+# Plugins
+
+@Metadata {
+    @Available("Swift", introduced: "5.6")
+}
+
+Extend package manager functionality with build or command plugins.  
+
+## Overview
+
+Some of Swift Package Manager's functionality can be extended through _plugins_.
+Write package plugins using the `PackagePlugin` API provided by the Swift Package Manager. <!-- link to docs needed -->
+This is similar to how the package manifest is implemented — as Swift code that runs as needed in order to produce the information package manager needs.
+
+Package manager defines two extension points for plugins:
+
+- term Build Plugin: Custom build tool tasks that provide commands to run before or during the build.
+  See <doc:EnableBuildPlugin> to see how to add an existing build plugin, or <doc:WritingBuildToolPlugin> to write your own.
+
+- term Command Plugin: Custom commands that you run using the `swift package` command line interface.
+  See <doc:EnableCommandPlugin> to see how to add an existing command plugin, or <doc:WritingCommandPlugin> to write your own.
+
+### Plugin Capabilities
+
+Plugins have access to a representation of the package model.
+Command plugins can also invoke services provided by package manager to build and test products and targets defined in the package to which the plugin is applied.
+
+Every plugin runs as a separate process from the package manager. 
+On platforms that support sandboxing, package manager wraps the plugin in a sandbox that prevents network access and attempts to write to arbitrary locations in the file system.
+All plugins can write to a temporary directory.
+
+Custom command plugins that need to modify the package source code can specify this requirement.
+If the user approves, package manager grants write access to the package directory.
+Build tool plugins can't modify the package source code.
+
+### Creating Plugins
+
+When creating a plugin, represent a plugin in the package manifest as a target of the `pluginTarget` type.
+If it should be available to other packages, also include a corresponding `pluginProduct` target.
+Source code for a plugin is normally located in a directory under the `Plugins` directory in the package, but this can be customized.
+
+A plugin declares which extension point it implements by defining the plugin's _capability_.
+This determines the entry point through which package manager will call it, and determines which actions the plugin can perform.
+
+### References
+
+- "Meet Swift Package plugins" [WWDC22 session](https://developer.apple.com/videos/play/wwdc2022-110359)
+- "Create Swift Package plugins" [WWDC22 session](https://developer.apple.com/videos/play/wwdc2022-110401)
+
+## Topics
+
+### Enabling Plugins
+
+- <doc:EnableCommandPlugin>
+- <doc:EnableBuildPlugin>
+
+### Writing Plugins
+
+- <doc:WritingCommandPlugin>
+- <doc:WritingBuildToolPlugin>

Sources/PackageManagerDocs/Documentation.docc/Plugins/EnableBuildPlugin.md

@@ -0,0 +1,60 @@
+# Enable a build plugin
+
+@Metadata {
+    @Available("Swift", introduced: "5.6")
+}
+
+Extend the package manager with a build plugin from another package.
+
+## Overview
+
+A package plugin is available to the package that defines it, and if there is a corresponding plugin product, it is also available to any other package that has a direct dependency on the package that defines it.
+
+### Add a dependency
+
+To use a plugin defined in another package, add a package dependency on the package that defines the plugin.
+For example, to use the [swift-openapi-generator](https://github.com/apple/swift-openapi-generator), add
+the following dependency:
+
+```swift
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        // other dependencies
+        .package(url: "https://github.com/apple/swift-openapi-generator",
+                 from: "1.0.0"),
+    ],
+    targets: [
+        // targets
+    ]
+)
+```
+
+
+This plugin can generate models and stubs for clients and servers from an OpenAPI definition file.
+
+### Identify the targets to enable
+
+Add the plugin to each target to which it should apply.
+For example, the following example enables the OpenAPI generator plugin on the executable target:
+
+```swift
+let package = Package(
+    name: "Example",
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator",
+                 from: "1.0.0"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "MyExample",
+            plugins: [
+                .plugin(name: "OpenAPIGenerator", 
+                        package: "swift-openapi-generator")
+            ]
+        )
+    ]
+)
+```
+When package manager builds the executable target, it calls the plugin and passes it a simplified version of the package model for the target to which it is applied.
+Any build commands returned by the plugin are be incorporated into the build graph and run at the appropriate time during the build.

Sources/PackageManagerDocs/Documentation.docc/Plugins/EnableCommandPlugin.md

@@ -0,0 +1,60 @@
+# Enable a command plugin
+
+@Metadata {
+    @Available("Swift", introduced: "5.6")
+}
+
+Extend package manager commands with a command plugin from another package.
+
+## Overview
+
+To get access to a plugin from another package, add a dependency on the package that provides the plugin.
+This lets the package access any plugins from the dependency.
+
+### Add a dependency
+
+For example, to enable the plugins from [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin), add it as a dependency:
+
+```swift
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        // other dependencies
+        .package(url: "https://github.com/swiftlang/swift-docc-plugin",
+                 from: "1.0.0"),
+    ],
+    targets: [
+        // targets
+    ]
+)
+```
+
+### View available plugins
+
+Run `swift package plugin --list` to see available plugins.
+For full documentation on the plugin command, see <doc:PackagePlugin>.
+
+Invoke an available plugin using `swift package` followed by the plugin, and provide any parameters or options required.
+For example, the following command invokes the `generate-documentation` command from [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin).
+
+```bash
+swift package generate-documentation
+```
+
+### Pass arguments and flags to the plugin
+
+Package manager passes all command line arguments and flags after the invocation verb to the plugin.
+
+For example, if your package has multiple targets you may want to specify a single target with the parameter: `--target`.
+An updated example that previews the hypothetical target `MyTarget`:
+
+```bash
+swift package generate-documentation --target MyTarget
+```
+
+### Exempting sandbox constraints
+
+Command plugins that need to write to the file system cause package manager to ask the user for approval if `swift package` is invoked from a console, or deny the request if it is not.
+Pass the flag `--allow-writing-to-package-directory` to the `swift package` invocation to allow the request without questions — this is particularly useful in a Continuous Integration environment.
+
+Similarly, use the `--allow-network-connections` flag to allow network connections without showing a prompt.