Migrate remaining content from documentation/Usage.md into DocC articles (#8734)

Migrate remaining content from documentation/Usage.md into DocC articles

### Motivation:

Migrate existing documentation from plain markdown into DocC and
slightly update content when outdated.

### Modifications:

Added the following new articles:
- Sources/PackageManagerDocs/Documentation.docc/BundlingResources.md
- Sources/PackageManagerDocs/Documentation.docc/CreatingSwiftPackage.md
-
Sources/PackageManagerDocs/Documentation.docc/Dependencies/EditingDependencyPackage.md
-
Sources/PackageManagerDocs/Documentation.docc/ReleasingPublishingAPackage.md
-
Sources/PackageManagerDocs/Documentation.docc/SettingSwiftToolsVersion.md
-
Sources/PackageManagerDocs/Documentation.docc/SwiftVersionSpecificPackaging.md
-
Sources/PackageManagerDocs/Documentation.docc/UsingBuildConfigurations.md
- Sources/PackageManagerDocs/Documentation.docc/UsingShellCompletion.md

Updated the following articles to accommodate the new articles:
- Sources/PackageManagerDocs/Documentation.docc/Documentation.md
- Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md
-
Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md

resolves #8593

---------

Co-authored-by: Bri Peticca <[email protected]>

Author: heckj

Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md

@@ -80,3 +80,4 @@ For more information on creating a binary target, see [Creating a multiplatform
 - <doc:ResolvingDependencyFailures>
 - <doc:AddingSystemLibraryDependency>
 - <doc:ExampleSystemLibraryPkgConfig>
+- <doc:EditingDependencyPackage>

Sources/PackageManagerDocs/Documentation.docc/BundlingResources.md

@@ -0,0 +1,82 @@
+# Bundling resources with a Swift package
+
+Add resource files to your Swift package and access them in your code.
+
+## Overview
+
+If you declare `// swift-tools-version: 5.3` or later in your `Package.swift` file, you can bundle resources alongside your source code in Swift packages.
+For example, Swift packages can contain asset catalogs, test fixtures, and so on.
+
+### Add resource files
+
+Package manager treats non-source files found in the target's sources directory as assets, scoped to that target.
+For example, any resources for the `MyLibrary` target reside by default in `Sources/MyLibrary`.
+To easily distinguish resources from source files, create and use a subfolder for the resources. 
+For example, put all resource files into a directory named `Resources`, resulting in all of your resource files residing at `Sources/MyLibrary/Resources`.
+
+### Explicitly declare or exclude resources
+
+To add a resource that the compiler doesn't handle automatically, explicitly declare it as a resource in your package manifest.
+If you're building your package with Xcode, it automatically handles a number of kinds of resources.
+
+For example, to include a file `text.txt` as a resource, add the file into `Sources/MyLibrary/Resources`.
+Then explicitly declare it as a package resource by adding the name of the file to the list of resources for your target:
+
+```swift
+targets: [
+    .target(
+        name: "MyLibrary",
+        resources: [
+            .process("Resources/text.txt")]
+    ),
+]
+```
+
+The example above uses  [process(_:localization:)](https://developer.apple.com/documentation/PackageDescription/Resource/process(_:localization:)) to identify the resource.
+When you explicitly declare a resource, choose a rule to determine how Swift treats the resource file.
+The options include:
+
+- term Process rule: For most use cases, use [process(_:localization:)](https://developer.apple.com/documentation/PackageDescription/Resource/process(_:localization:)). This requests the compiler to apply any processing known for the type of resource, according to the platform you’re building the package for. 
+For example, Xcode may optimize image files for a platform that supports such optimizations.
+If you apply the process rule to a directory’s path, Xcode applies the rule recursively to all files within the directory. 
+If no special processing is available for a resource, the compiler copies the resource as is to the resource bundle’s top-level directory.
+
+- term Copy rule: Some Swift packages may require a resource file to remain untouched or to retain a certain directory structure for resources. 
+Use the [copy(_:)](https://developer.apple.com/documentation/PackageDescription/Resource/copy(_:)) function to apply this rule and copy the resource as is to the top level of the resource bundle. 
+If you pass a directory path to the copy rule, the compiler retains the directory’s structure.
+
+If a file resides inside a target’s folder and you don’t want it to be a package resource, pass it to the target initializer’s `exclude` parameter.
+For example, if you have a file called `instructions.md` in the sources directory, meant only for local use and not intended to be bundled, use `exclude`:
+
+```swift
+targets: [
+    .target(
+        name: "MyLibrary",
+        exclude:["instructions.md"]
+    ),
+]
+```
+
+In general, avoid placing files that aren’t resources in a target's source folder. 
+If that's not feasible, avoid excluding every file individually, place all files you want to exclude in a directory, and add the directory path to the array of excluded files.
+Swift Package Manager warns you about files it doesn't recognize in a target's `Sources` directory.
+
+### Access a resource in code
+
+If a target includes resources, the compiler creates a resource bundle and an internal static extension on [Bundle](https://developer.apple.com/documentation/Foundation/Bundle) to access it for each module. 
+Use the extension to locate package resources.
+For example, use the following to retrieve the URL to a property list you bundle with your package:
+
+```swift
+let settingsURL = Bundle.module.url(forResource: "settings", withExtension: "plist")
+```
+
+> Important: Always use `Bundle.module` to access resources.
+> A package shouldn’t make assumptions about the exact location of a resource.
+
+If you want to make a package resource available to apps that depend on your Swift package, declare a public constant for it.
+For example, use the following to expose a property list file to apps that use your Swift package:
+
+```swift
+let settingsURL = Bundle.module.url(forResource: "settings", withExtension: "plist")
+```

Sources/PackageManagerDocs/Documentation.docc/CreatingSwiftPackage.md

@@ -0,0 +1,83 @@
+# Creating a Swift package
+
+Bundle executable or shareable code into a standalone Swift package.
+
+## Overview
+
+A Swift package is a directory that contains sources, dependencies, and has a `Package.swift` manifest file at its root.
+Swift packages can provide libraries, executables, tests, plugins, and macros.
+The package manifest defines what is in the package, which is itself written in Swift.
+The [API reference for PackageDescription](https://developer.apple.com/documentation/packagedescription) defines the types, properties, and functions that go into assembling a package manifest.
+
+### Creating a Library Package
+
+Swift package manager supports creating packages using <doc:PackageInit>.
+By default, the package manager creates a package structure focused on providing a library.
+For example, you can create a directory and run the command `swift package init` to create a package:
+
+```bash
+$ mkdir MyPackage
+$ cd MyPackage
+$ swift package init
+```
+
+The structure provided follows package manager conventions, and provides a fully operational example.
+In addition to the package manifest, Swift sources are collected by target name under the `Sources` directory, and tests collected, also by target name, under the `Tests` directory:
+
+```
+├── Package.swift
+├── Sources
+│   └── MyPackage
+│       └── MyPackage.swift
+└── Tests
+    └── MyPackageTests
+        └── MyPackageTests.swift
+```
+
+You can immediately use both of <doc:SwiftBuild> and <doc:SwiftTest>:
+
+```bash
+$ swift build
+$ swift test
+```
+
+### Creating an Executable Package
+
+Swift Package Manager can also create a new package with a simplified structure focused on creating executables.
+For example, create a directory and run the `init` command with the option `--type executable` to get a package that provides a "Hello World" executable:
+
+```bash
+$ mkdir MyExecutable
+$ cd MyExecutable
+$ swift package init --type executable
+$ swift run
+Hello, World!
+```
+
+There is an additional option for creating a command-line executable based on the `swift-argument-parser`, convenient for parsing command line arguments and structuring commands.
+Use `tool` for the `type` option in <doc:PackageInit>.
+Like the `executable` template, it is fully operational and also prints "Hello World".
+
+### Creating a Macro Package
+
+Swift Package Manager can generate boilerplate for custom macros:
+
+```bash
+$ mkdir MyMacro
+$ cd MyMacro
+$ swift package init --type macro
+$ swift build
+$ swift run
+The value 42 was produced by the code "a + b"
+```
+
+This creates a package with:
+
+- A `.macro` type target with its required dependencies on [swift-syntax](https://github.com/swiftlang/swift-syntax),
+- A library `.target`  containing the macro's code.
+- An `.executableTarget` for running the macro.
+- A `.testTarget` for test the macro implementation.
+
+The sample macro, `StringifyMacro`, is documented in the Swift Evolution proposal for [Expression Macros](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0382-expression-macros.md)
+and the WWDC [Write Swift macros](https://developer.apple.com/videos/play/wwdc2023/10166) video.
+For further documentation, see macros in [The Swift Programming Language](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/macros/) book.

Sources/PackageManagerDocs/Documentation.docc/Dependencies/EditingDependencyPackage.md

@@ -0,0 +1,81 @@
+# Editing a remote dependency used in a Swift package
+
+Temporarily switch a remote dependency to local in order to edit the dependency.
+
+## Overview
+
+Swift package manager supports editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API).
+The package manager moves the dependency into a location under the `Packages/` directory where it can be edited.
+
+For the packages which are in the editable state, `swift build` uses the exact sources in this directory to build, regardless of their state, Git repository status, tags, or the tag desired by dependency resolution.
+In other words, this _just builds_ against the sources that are present.
+When an editable package is present, it is used to satisfy all instances of that package in the dependency graph.
+It is possible to edit all, some, or none of the packages in a dependency graph, without restriction.
+
+Editable packages are best used to do experimentation with dependency code, or to create and submit a patch in the dependency owner's repository (upstream).
+There are two ways to put a package in editable state, using <doc:PackageEdit>.
+The first example creates a branch called `bugFix` from the currently resolved version and puts the dependency `PlayingCard` in the `Packages/` directory:
+
+```bash
+$ swift package edit PlayingCard --branch bugFix
+```
+
+The second is similar, except that the Package Manager leaves the dependency at a detached HEAD at the commit you specified.
+
+```bash
+$ swift package edit PlayingCard --revision 969c6a9
+```
+
+> Note: If the branch or revision option is not provided, the Package Manager uses the currently resolved version on a detached HEAD.
+
+Once a package is in an editable state, you can navigate to the directory `Packages/PlayingCard` to make changes, build and then push the changes or open a pull request to the upstream repository.
+
+You can end editing a package with <doc:PackageUnedit>.
+
+
+```bash
+$ swift package unedit PlayingCard
+```
+
+This removes the edited dependency from `Packages/` and restores the originally resolved version.
+
+This command fails if you have uncommitted changes or changes which are not pushed to the remote repository.
+If you want to discard these changes and unedit, use the `--force` option:
+
+```bash
+$ swift package unedit PlayingCard --force
+```
+
+### Top of Tree Development
+
+This feature allows overriding a dependency with a local checkout on the filesystem.
+This checkout is completely unmanaged by the package manager and is used as-is.
+The only requirement is that the package name in the overridden checkout shouldn't change.
+This is useful when developing multiple packages in tandem, or when working on packages alongside an
+application.
+
+The command to attach (or create) a local checkout is:
+
+```bash
+$ swift package edit <package name> \
+    --path <path/to/dependency>
+```
+
+For example, if `PlayingCard` depends on `swift-collections` and you have a checkout of `swift-collections` at
+`/workspace/swift-collections`:
+
+```bash
+$ swift package edit swift-collections \
+    --path /workspace/swift-collections
+```
+
+A checkout of `swift-collections` is created if it doesn't exist at the path you specified.
+If a checkout exists, package manager validates the package name at the given path and attaches to it.
+
+The package manager also creates a symlink in the `Packages/` directory to the checkout path.
+
+Use <doc:PackageUnedit> command to stop using the local checkout:
+
+```bash
+$ swift package unedit swift-collections
+```

Sources/PackageManagerDocs/Documentation.docc/Documentation.md

@@ -20,9 +20,16 @@ The Swift Package Manager lets you share your code as a package, depend on and u
 
 ### Guides
 
+- <doc:CreatingSwiftPackage>
+- <doc:SettingSwiftToolsVersion>
 - <doc:AddingDependencies>
 - <doc:ResolvingPackageVersions>
 - <doc:CreatingCLanguageTargets>
+- <doc:UsingBuildConfigurations>
+- <doc:SwiftVersionSpecificPackaging>
+- <doc:BundlingResources>
+- <doc:ReleasingPublishingAPackage>
+- <doc:UsingShellCompletion>
 - <doc:SwiftPMAsALibrary>
 - <doc:ModuleAliasing>
 
@@ -46,5 +53,3 @@ The Swift Package Manager lets you share your code as a package, depend on and u
 - <doc:SwiftPackageRegistryCommands>
 - <doc:SwiftPackageCollectionCommands>
 - <doc:SwiftRun>
-
-### Design

Sources/PackageManagerDocs/Documentation.docc/ReleasingPublishingAPackage.md

@@ -0,0 +1,27 @@
+# Releasing and publishing a Swift package
+
+Share a specific version of your package.
+
+## Overview
+
+Swift Package Manager expects a package to be remotely shared as a single Git repository, with a tag that conforms to a full semantic version, and a `Package.swift` manifest in the root of the repository.
+
+<!-- TODO: need a reference to sharing a dependency through a swift registry -->
+
+To publish a package that is hosted in a Git repository, create and push a semantic version tag.
+Swift package manager expects the tag to be a full semantic version, that includes major, minor, and patch versions in the tag.
+
+The following commands illustrate adding a tag `1.0.0` and pushing those tags to the remote repository:
+
+```bash
+$ git tag 1.0.0
+$ git push origin --tags
+```
+
+> Warning: A tag in the form of `1.0` isn't recognized by Swift Package Manager as a complete semantic version.
+> Include all three integers reflecting the major, minor, and patch version information.
+
+With the tag in place, other packages can depend on the package you tagged through your source repository.
+An example of a published package can be found at [github.com/apple/example-package-playingcard](https://github.com/apple/example-package-playingcard/) with multiple releases available.
+
+To read more about adding a dependency to your package, read <doc:AddingDependencies>.

Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md

@@ -1,4 +1,4 @@
-# Resolving and updating package versions
+# Resolving and updating dependencies
 
 Coordinate and constrain dependencies for your package.
 
@@ -30,3 +30,4 @@ If the `Package.resolved` file does exist, any command that requires dependencie
 
 The `Package.resolved` doesn't constrain upstream dependencies of the package. 
 For example, if your package presents a library and has `Package.resolved` checked in, those versions are ignored by the package that depends on your library, and the latest eligible versions are chosen.
+For more information on constraining dependency versions, see <doc:AddingDependencies>.

Sources/PackageManagerDocs/Documentation.docc/SettingSwiftToolsVersion.md

@@ -0,0 +1,28 @@
+# Setting the Swift tools version
+
+Define the minimum version of the swift compiler required for your package.
+
+## Overview
+
+The tools version declares the minimum version of the Swift compiler required to
+use the package, as well as how parse the `Package.swift` manifest.
+When you create a new package using <doc:PackageInit>, the minimum version is set automatically to the current version.
+The version is specified on the first line of the manifest with the comment `// swift-tools-version:` and the version for the Swift compiler.
+The version is a semantic version, with the exception that a patch version is inferred to be `0` if you don't specify it.
+
+For example, the following line asserts the package requires the Swift compiler version 6.1 or later:
+
+```swift
+// swift-tools-version:6.1
+```
+
+### Resolving dependencies with different tools versions
+
+When resolving package dependencies, if the tools version of a dependency is greater than the version in use, that version of the dependency is ineligible and dependency resolution continues with evaluating the next-best version.
+
+If no tools version of a dependency, which otherwise meets the package version requirements, supports the version of the Swift tools in use, the package manager presents a dependency resolution error.
+For more information on providing package manifests for specific Swift versions, see <doc:SwiftVersionSpecificPackaging>.
+
+### Adjusting the tools version.
+
+Edit the `Package.swift` to adjust the version, or use <doc:PackageToolsVersion> to report or set the the tools version.