Support `--output-path` when building documentation for multiple targets.

[d-ronnqvist]

Bug/issue #, if applicable:

Summary

Support passing a custom --output-path value when building documentation for multiple targets.

This is technically unrelated to support for combined documentation archives, but it's more likely that developers will pass a custom output path when building combined documentation for multiple targets.

I implemented this PR in steps:

• First https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/e66ee31902270dc48b3cfeb505ee16ebd24bfbe8 added support for --output-path only when building combined documentation.

• Then https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/39d886c10f2bc4deb0f9a077e1f8ae6bb3f0a43a extended that support to non-combined documentation builds as well.

  This is technically a change in behavior—each target will output in a subdirectory of the specified output path. However, I considered the old behavior incorrect and not worth preserving because it was broken—each target wrote over the previous target's output, resulting in only one target's output.

Additionally, this PR makes the following changes

• https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/78fef3e93b18cc58ddf8888c209acc8b966e6f8a conditionally customizes the synthesized landing page using https://github.com/swiftlang/swift-docc/pull/1011
• https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/3aeb6751da007ecc6c7eb9b8402f71c4135b3ed9 Refines the command output to add more information to the build tasks and print the resulting archive paths the same when building one target, many targets, or a combined archive.
• https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/099fed3dc133783ea45cb961c96e080c9f0b4c03 Enables task parallelism when building documentation for more than one target
• https://github.com/swiftlang/swift-docc-plugin/pull/89/commits/1df6bb8b76cb2277639f3a48b440a0cc3bb96d3c adds two additional integration tests that verifies building combined documentation with and without a custom output path.

Dependencies

This builds on top of #87 and #88. The new changes in this PR start with https://github.com/swiftlang/swift-docc-plugin/commit/e66ee31902270dc48b3cfeb505ee16ebd24bfbe8 and onwards. You can see that subset of the diff here.

Additionally, this PR conditionally uses some new functionality in https://github.com/swiftlang/swift-docc/pull/1011.

Testing

There are 3 behaviors to test in this PR

• building documentation for one target with a custom output path
• building documentation for multiple targets with a custom output path
• building combined documentation with a custom output path

Note that in all cases you need to disable package sandboxing to use a custom output path.

You can use the package plugin repo itself to test this.

Single target

Build documentation for one target with a custom output path

swift package \
  --disable-sandbox \
  generate-documentation \
  --target Snippets \
  --output-path MyOutputDir

After the build succeeds, the "MyOutputDir" directory should contain the content of the Snippets target's documentation.

Multiple targets

Build documentation for two (or more) targets with a custom output path

swift package \
  --disable-sandbox \
  generate-documentation \
  --target Snippets \
  --target SwiftDocCPlugin \
  --output-path MyOutputDir

After the build succeeds, the "MyOutputDir" directory should contain the two subdirectories named "Snippets.doccarchive" and "SwiftDocCPlugin.doccarchive" that each contain that target's documentation.

Combined targets

Build combined documentation for two (or more) targets with a custom output path

swift package \
  --disable-sandbox \
  generate-documentation \
  --target Snippets \
  --target SwiftDocCPlugin \
  --enable-experimental-combined-documentation \
  --output-path MyOutputDir

After the build succeeds, the "MyOutputDir" directory should contain the content of the combined documentation archive.

The plugin only prints the combined archives's output path. It doesn't print the individual target's output paths, even though they were built to produce the combined archive.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• [x] Added tests
• [x] Ran the ./bin/test script and it succeeded
• ~[ ] Updated documentation if necessary~ Not applicable.

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test