Migrate PackageCollections.md to DocC (#8715)

The covers the porting of content for `PackageCollections.md` into our
DocC catalog and fixes #8589.

The new guide article for `PackageCollections` exists under
`Sources/PackageManagerDocs/Documentation.docc/PackageCollections.md`
and touches on creating, publishing, signing/protecting, and modifying
package collections. Below the overview there is a list of subcommands
available on the `swift package-collection` tool with links navigating
to the Swift commands documentation.

Each of the `PackageCollection` CLI commands have been augmented with
supplementary information about how to use the subcommand (if
applicable), all of which is taken from the original
`/Documentation/PackageCollections.md` markdown file.

Some links within these guides either still reference the old links in
the original `Documentation/PackageCollections.md` file or are
placeholders - both are marked with a `TODO` to update these links once
other issues under #8603 are completed and we can replace the links with
the appropriate DocC equivalent.

Some content in these guides are also taken from
`Sources/PackageCollectionsModel/Formats/v1`.

Author: bripeticca

Sources/PackageManagerDocs/Documentation.docc/Documentation.md

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

Sources/PackageManagerDocs/Documentation.docc/PackageCollections.md

@@ -6,6 +6,98 @@
 
 Add a new collection.
 
+## Overview
+
+This subcommand adds a package collection hosted on the web (HTTPS required):
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json
+Added "Sample Package Collection" to your package collections.
+```
+
+Or found in the local file system:
+
+```bash
+$ swift package-collection add file:///absolute/path/to/packages.json
+Added "Sample Package Collection" to your package collections.
+```
+
+The optional `order` hint can be used to order collections and may potentially influence ranking in search results:
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json [--order N]
+Added "Sample Package Collection" to your package collections.
+```
+
+### Signed package collections
+
+Package collection publishers may [sign a collection to protect its contents](<doc:PackageCollections#Signing-and-protecting-package-collections>) from being tampered with. 
+If a collection is signed, SwiftPM will check that the 
+signature is valid before importing it and return an error if any of these fails:
+- The file's contents, signature excluded, must match what was used to generate the signature. 
+In other words, this checks to see if the collection has been altered since it was signed.
+- The signing certificate must meet all the [requirements](<doc:PackageCollections#Requirements-on-signing-certificate>).
+
+```bash
+$ swift package-collection add https://www.example.com/bad-packages.json
+The collection's signature is invalid. If you would like to continue please rerun command with '--skip-signature-check'.
+```
+
+Users may continue adding the collection despite the error or preemptively skip the signature check on a package collection by passing the `--skip-signature-check` flag:
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json --skip-signature-check
+```
+
+For package collections hosted on the web, publishers may ask SwiftPM to [enforce the signature requirement](<doc:PackageCollections#Protecting-package-collections>). If a package collection is
+expected to be signed but it isn't, user will see the following error message:
+
+```bash
+$ swift package-collection add https://www.example.com/bad-packages.json
+The collection is missing required signature, which means it might have been compromised.
+```
+
+Users should NOT add the package collection in this case.
+
+##### Trusted root certificates
+
+Since generating a collection signature requires a certificate, part of the signature check involves validating the certificate and its chain and making sure that the root certificate is trusted.
+
+On Apple platforms, all root certificates that come preinstalled with the OS are automatically trusted. Users may include additional certificates to trust by placing 
+them in the `~/.swiftpm/config/trust-root-certs` directory. 
+
+On non-Apple platforms, there are no trusted root certificates by default other than those shipped with the [certificate-pinning configuration](<doc:PackageCollections#Protecting-package-collections>). Only those 
+found in `~/.swiftpm/config/trust-root-certs` are trusted. This means that the signature check will always fail unless the `trust-root-certs` directory is set up:
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json
+The collection's signature cannot be verified due to missing configuration.
+```
+
+Users can explicitly specify they trust a publisher and any collections they publish, by obtaining that publisher's root certificate and saving it to `~/.swiftpm/config/trust-root-certs`. The 
+root certificates must be DER-encoded. Since SwiftPM trusts all certificate chains under a root, depending on what roots are installed, some publishers may already be trusted implicitly and 
+users don't need to explicitly specify each one. 
+
+#### Unsigned package collections
+
+Users will get an error when trying to add an unsigned package collection:
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json
+The collection is not signed. If you would still like to add it please rerun 'add' with '--trust-unsigned'.
+```
+
+To continue user must confirm their trust by passing the `--trust-unsigned` flag:
+
+```bash
+$ swift package-collection add https://www.example.com/packages.json --trust-unsigned
+```
+
+The `--skip-signature-check` flag has no effects on unsigned collections.
+
+
+## Usage
+
 ```
 package-collection add <collection-url> [--order=<order>] [--trust-unsigned] [--skip-signature-check] [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>]     [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...]   [--enable-dependency-cache|disable-dependency-cache]  [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry]  [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]    [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]   [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store]   [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>]      [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help]
 ```

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

@@ -6,6 +6,78 @@
 
 Get metadata for a collection or a package included in an imported collection.
 
+## Overview
+
+This subcommand shows metadata for a collection or a package included in an imported collection. The result can optionally be returned as JSON using `--json` for
+integration into other tools.
+
+### Metadata and packages of a collection
+
+`describe` can be used for both collections that have been previously added to the list of the user's configured collections, as well as to preview any other collections.
+
+```bash
+$ swift package-collection describe [--json] https://www.example.com/packages.json
+Name: Sample Package Collection
+Source: https://www.example.com/packages.json
+Description: ...
+Keywords: best, packages
+Created At: 2020-05-30 12:33
+Packages:
+    https://github.com/jpsim/yams
+    ...
+```
+
+#### Signed package collections
+
+If a collection is signed, SwiftPM will check that the signature is valid before showing a preview.
+
+```bash
+$ swift package-collection describe https://www.example.com/bad-packages.json
+The collection's signature is invalid. If you would like to continue please rerun command with '--skip-signature-check'.
+```
+
+Users may continue previewing the collection despite the error or preemptively skip the signature check on a package collection by passing the `--skip-signature-check` flag:
+
+```bash
+$ swift package-collection describe https://www.example.com/packages.json --skip-signature-check
+```
+
+### Metadata of a package
+
+`describe` can also show the metadata of a package included in an imported collection:
+
+```bash
+$ swift package-collection describe [--json] https://github.com/jpsim/yams
+Description: A sweet and swifty YAML parser built on LibYAML.
+Available Versions: 4.0.0, 3.0.0, ...
+Stars: 14
+Readme: https://github.com/jpsim/Yams/blob/master/README.md
+Authors: @norio-nomura, @jpsim
+--------------------------------------------------------------
+Latest Version: 4.0.0
+Package Name: Yams
+Modules: Yams, CYaml
+Supported Platforms: iOS, macOS, Linux, tvOS, watchOS
+Supported Swift Versions: 5.3, 5.2, 5.1, 5.0
+License: MIT
+```
+
+### Metadata of a package version
+
+User may view additional metadata for a package version by passing `--version`:
+
+```bash
+$ swift package-collection describe [--json] --version 4.0.0 https://github.com/jpsim/yams
+Package Name: Yams
+Version: 4.0.0
+Modules: Yams, CYaml
+Supported Platforms: iOS, macOS, Linux, tvOS, watchOS
+Supported Swift Versions: 5.3, 5.2, 5.1, 5.0
+License: MIT
+```
+
+## Usage
+
 ```
 package-collection describe [--json] <package-url> [--version=<version>] [--skip-signature-check] [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>]     [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...]   [--enable-dependency-cache|disable-dependency-cache]  [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry]  [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]    [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]   [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store]   [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>]      [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help]
 ```

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

@@ -6,6 +6,20 @@
 
 List configured collections.
 
+## Overview
+
+This subcommand lists all collections that are configured by the user:
+
+```bash
+$ swift package-collection list [--json]
+Sample Package Collection - https://example.com/packages.json
+...
+```
+
+The result can optionally be returned as JSON using `--json` for integration into other tools.
+
+## Usage
+
 ```
 package-collection list [--json] [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>]     [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...]   [--enable-dependency-cache|disable-dependency-cache]  [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry]  [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]    [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]   [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store]   [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>]      [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help]
 ```

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

@@ -6,6 +6,20 @@
 
 Refresh configured collections.
 
+## Overview
+
+This subcommand refreshes any cached data manually:
+
+```bash
+$ swift package-collection refresh
+Refreshed 5 configured package collections.
+```
+
+SwiftPM will also automatically refresh data under various conditions, but some queries such as search will rely on locally cached data.
+
+
+## Usage
+
 ```
 package-collection refresh [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>]     [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...]   [--enable-dependency-cache|disable-dependency-cache]  [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry]  [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]    [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]   [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store]   [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>]      [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help]
 ```

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

@@ -6,6 +6,17 @@
 
 Remove a configured collection.
 
+## Overview
+
+This subcommand removes a collection from the user's list of configured collections:
+
+```bash
+$ swift package-collection remove https://www.example.com/packages.json
+Removed "Sample Package Collection" from your package collections.
+```
+
+## Usage
+
 ```
 package-collection remove <collection-url> [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>]     [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...]   [--enable-dependency-cache|disable-dependency-cache]  [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry]  [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...]    [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>]   [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store]   [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>]      [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help]
 ```