@bitjammer That makes sense. Would it be reasonable (or even feasible) to add a new executable tool to SymbolKit that can do this? The plugin would have access to any executables vended by SymbolKit if it depended on it. And SwiftPM command plugins have an understanding of the package model so the Swift-DocC plugin should know what files to point that hypothetical SymbolKit executable at.
For the same reasons as DocC, I don't think SymbolKit should be responsible for parsing for understanding Swift files.
Ah right. Agreed. 
An alternative would be to add an executable product to the Swift-DocC plugin that itself depends on SymbolKit. Then the actual plugin code can just invoke the executable.
At that point though- it seems like we should just create another Package that's dedicated to that purpose and have the plugin depend on that. That would also allow other tools (besides the Swift-DocC plugin) to build upon snippet symbol graphs.
Oh, so you can have other kinds of targets in the plugin package? I thought the entire package wasn't allowed to have dependencies. Hm, perhaps that's something to consider. It still seems strange to use an executable for use for that, though. We can revisit this soon though! Thanks for clarifying.
1 Like
Is this currently possible? Because I'd love for a plugin to call its own executable (even though it's sandboxed). That'd lower the barrier of integrating codegen such as sourcery by a lot.
Yeah, it is possible to make a plugin depend on a binary executable, it looks something like this:
// swift-tools-version: 5.6
import PackageDescription
let package = Package(
name: "SwiftGen",
targets: [
/// Package plugin that tells SwiftPM how to run `swiftgen` based on
/// the configuration file. Client targets use this plugin by listing
/// it in their `plugins` parameter.
.plugin(
name: "SwiftGenPlugin",
capability: .buildTool(),
dependencies: ["SwiftGen"]
),
/// Binary target that provides the built SwiftGen executables.
.binaryTarget(
name: "SwiftGen",
url: "https://url/to/the/built/swiftgen-executables.zip",
checksum: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
),
]
)
It's the SwiftGen example from the plugins proposal: swift-evolution/0303-swiftpm-extensible-build-tools.md at main · apple/swift-evolution · GitHub
3 Likes
Hi all! Quick update here.
The Swift-DocC Plugin has just been updated for the latest API changes in the SwiftPM command plugin infrastructure. I think a few of you noticed that the Swift-DocC plugin broke with the latest Xcode beta (CC: @Joseph_Heck), so if you update to the latest version on main, you should find things working again.
The SwiftPM command plugin UX has been updated so that options like --target and --product are passed directly to the plugin instead of to the package manager itself.
This means that instead of invoking the Swift-DocC plugin with something like:
swift package --target SwiftMarkdown generate-documentation
you would now do:
swift package generate-documentation --target SwiftMarkdown
Besides being (in my opinion) a generally more user-friendly command-line experience, this allows plugins to be a little smarter about choosing which targets to build. For example, now when a user invokes the basic
swift package generate-documentation
the plugin will generate documentation for all targets used in your package, including those defined by dependencies.
This also allows users of the plugin to specify products and targets of dependencies which makes doing something like
swift package --disable-sandbox preview-documetnation --product ArgumentParser
possible for packages that import ArgumentParser.
I think this will be great for improving the experience of learning about a new package you're depending on.
Please let me know if you run into any issues! As we approach the release of Swift 5.6, we're also working towards the 1.0 release of the Swift-DocC plugin so any and all feedback is very much appreciated.
- Ethan
7 Likes
The Swift-DocC Plugin has officially reached version 1.0 along with the release of Swift 5.6! 
A special thanks here to everyone who provided feedback as we worked towards the first stable release. I'm looking forward to continuing to refine the plugin with you all in future versions.
In the meantime, you can add the the plugin to your own package with:
let package = Package(
// name, platforms, products, etc.
dependencies: [
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
],
targets: [
// targets
]
)
And start generating Swift-DocC documentation with:
swift package generate-documentation
As always, see the repository on GitHub and the documentation site for more information.
- Ethan
11 Likes
Amazing work, this is super exciting!
1 Like
Is it the current limitation that I cannot generate the documentation for my package that uses UIKit. While generating I get:
... error: no such module 'UIKit'
import UIKit
Same as when running swift build but in this case, I can pass options to properly build
swift build -Xswiftc "-sdk" -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" -Xswiftc "-target" -Xswiftc "x86_64-apple-ios13.0-simulator"
I tried to pass the same params to generate documentation but it didn't help
swift package generate-documentation -Xswiftc "-sdk" -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" -Xswiftc "-target" -Xswiftc "x86_64-apple-ios13.0-simulator"
Update:
After changing the order of the build options the build completes but the documentation is not generated (from Xcode works though)
swift package -Xswiftc "-sdk" -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" -Xswiftc "-target" -Xswiftc "x86_64-apple-ios15.3-simulator" --allow-writing-to-directory ./docs generate-documentation --target UIEnvironment
Building for debugging...
Build complete! (0.09s)
Generating documentation for 'UIEnvironment'...
Building for debugging...
Build complete! (0.07s)
error: 'UIEnvironment' does not contain any documentable symbols or a DocC catalog and will not produce documentation
1 Like
To build docs for iOS you need to run xcodebuild:
xcodebuild docbuild \
-scheme UIEnvironment \
-destination 'generic/platform=ios'
Via Building multi-platform documentation with DocC | Daniel Saidi
3 Likes