Update documentation generate script

[Kyle-Ye]

See swiftlang/swift-markdown#149 (comment)

Summary

Update the documentation generate script to use swift-docc-plugin.

The hand write script to call docc directly is tricky and may be out of date to enjoy the latest feature of docc. Instead we prefer to use swift-docc-plugin.

After we add SymbolKit as a dependency of swift-docc-plugin, we can't directly use swift-docc-plugin in this Package. So this PR add a new Package.swift to avoid such circle dependency issue.

Testing

Confirm the script build and work as expected.

git fetch
git worktree add --checkout gh-pages origin/gh-pages
export SWIFT_DOCC_SYMBOLKIT_ROOT=$PWD
swift package \
    --package-path Documentation \
    --allow-writing-to-directory "$SWIFT_DOCC_SYMBOLKIT_ROOT/gh-pages/docs" \
    generate-documentation \
    --target SymbolKit \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path swift-docc-symbolkit \
    --output-path "$SWIFT_DOCC_SYMBOLKIT_ROOT/gh-pages/docs"

[ethan-kusters]

Smart! I like this a lot – we should definitely offer this as a solution to folks who want to use the plugin for building docs but don't want to add an additional dependency.

For SymbolKit specifically – I'm concerned this may break in the future since the swift-docc-plugin itself depends on SymbolKit. I'm seeing this in the build logs:

warning: 'swift-docc-plugin': 'swift-docc-plugin' dependency on 'https://github.com/apple/swift-docc-symbolkit' conflicts with dependency on '/Users/ekusters/Developer/swift-docc-symbolkit' which has the same identity 'swift-docc-symbolkit'. this will be escalated to an error in future versions of SwiftPM.

What do you think?

[Kyle-Ye]

Smart! I like this a lot – we should definitely offer this as a solution to folks who want to use the plugin for building docs but don't want to add an additional dependency.

For SymbolKit specifically – I'm concerned this may break in the future since the swift-docc-plugin itself depends on SymbolKit. I'm seeing this in the build logs:

warning: 'swift-docc-plugin': 'swift-docc-plugin' dependency on 'https://github.com/apple/swift-docc-symbolkit' conflicts with dependency on '/Users/ekusters/Developer/swift-docc-symbolkit' which has the same identity 'swift-docc-symbolkit'. this will be escalated to an error in future versions of SwiftPM.

What do you think?

Yes. I also noticed this warning locally. (Forgot to link it to the body of the PR)

Can we discuss this issue with folks in SwiftPM team to offer some API to fix it?

We have moduleAliases on Target.Dependency. And I'd to propose to add a new API for Package.Dependency - package(name:path:id:)

eg.

.package(name: "SymbolKit", path: "../."),
⬇️
.package(name: "SymbolKit", path: "../.", id: "SymbolKitLocal")

Thus the Package.swift will update to the following

let package = Package(
    name: "Documentation",
    dependencies: [
        .package(name: "SymbolKit", path: "../.", id: "SymbolKitLocal"),
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
    ],
    targets: [
        .target(
            name: "Empty",
            dependencies: [
                .product(name: "SymbolKit", package: "SymbolKitLocal"),
            ],
            path: "Empty"
        )
    ]
)

[Kyle-Ye]

Another way to fix this is split snippet-extract to its own Package file so that swift-docc-plugin would not have a dependency on swift-docc-symbolkit anymore.

https://github.com/apple/swift-docc-plugin/blob/3aad4aabc42835f09f600bb17070f6a11bc84180/Package.swift#L75-L80

Ah, since the plugin itself has a dependency on snippet-extract, we can't just move it out the main Package.swift. 🥲