[1.0] Add DocC documentation bundles

[lorentey]

Add DocC bundles for all public targets of this package.

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (if appropriate).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• I've updated the documentation if necessary.

[lorentey]

@swift-ci test

[lorentey]

Cc @yim-lee

[yim-lee]

@finestructure Would adding DocC bundle to the exclude list (because they generate warnings in older versions of Swift and we don't want to add versioned Package.swift just yet) interfere with hosting on SwiftPackageIndex.com?

[finestructure]

I've checked the tip of this PR and docc still generates the docs regardless, so this won't be a problem:

========================================
Checkout
========================================
Clone URL: https://github.com/apple/swift-collections
Reference: b4c1070741a119654864b736268c3f03f6799a1b
<- snip ->
========================================
GenerateDocs
========================================
Generating docs at path:  /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b
Repository:               apple/swift-collections
Swift version used:       5.7
Target:                   Collections
Fetching https://github.com/apple/swift-docc-plugin from cache
Fetched https://github.com/apple/swift-docc-plugin (0.74s)
Computing version for https://github.com/apple/swift-docc-plugin
Computed https://github.com/apple/swift-docc-plugin at 1.0.0 (0.48s)
Creating working copy for https://github.com/apple/swift-docc-plugin
Working copy of https://github.com/apple/swift-docc-plugin resolved at 1.0.0
Building for debugging...
<- snip ->
Build complete! (1.06s)
Generating documentation for 'Collections'...
Converting documentation...
Conversion complete! (0.03s)
Generated DocC archive at '/private/var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b'
Target:                   DequeModule
Building for debugging...
Build complete! (0.09s)
Generating documentation for 'DequeModule'...
Converting documentation...
Conversion complete! (0.15s)
Generated DocC archive at '/private/var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b'
Successfully merged into /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs-staging/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b/index/index.json
Target:                   OrderedCollections
Building for debugging...
Build complete! (0.09s)
Generating documentation for 'OrderedCollections'...
Converting documentation...
Conversion complete! (0.57s)
Generated DocC archive at '/private/var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b'
Successfully merged into /var/folders/nk/tlpts6bs799038htr6rx1xnc0000gn/T/AD3353BD-9650-4E82-884E-8983E40CDE2E/checkout/.docs-staging/apple/swift-collections/b4c1070741a119654864b736268c3f03f6799a1b/index/index.json

[finestructure]

Hold on, that doesn't necessarily mean the docc bundle and its articles would be included. I'll confirm.

[finestructure]

Yes, this does indeed strip out the landing page:

vs without the exclude:

Generated via

swift package --disable-sandbox plugin preview-documentation --target Collections

[finestructure]

A hacky workaround over adding a versioned manifest could be adding this at the end of the manifest:

#if swift(<5.7)
for target in package.targets.filter({ ["Collections" /* extend as needed */ ].contains($0.name) }) {
    package.targets[0].exclude = ["CMakeLists.txt", "\(target.name).docc"]
}
#endif

[lorentey]

Hm, that workaround looked promising at first, but it would still generate unhandled file warnings in 5.7+.

I think I'll just have to add a versioned manifest for SPMs ≧ 5.5 -- that will need a bit of more validation testing before I tag a new release, but it'll work!

[yim-lee]

Thanks @finestructure @lorentey!

[lorentey]

@swift-ci test