swiftlang / swift-docc-plugin

Swift Package Manager command plugin for Swift-DocC
https://swiftpackageindex.com/swiftlang/swift-docc-plugin/documentation/swiftdoccplugin
Apache License 2.0
323 stars 52 forks source link

New `--include-extended-types` changes seems to break `--additional-symbol-graph-dir` #60

Open NachoSoto opened 1 year ago

NachoSoto commented 1 year ago

Prior to version 1.2, we were generating our docs using additional-symbol-graph-dir. This is how we built the symbol graph:

sh("swift",
    "build",
    "--target", "RevenueCat",
    "--configuration", "debug", # Necessary for debug-only symbols
    # Build for iOS instead of the default macOS. This ensures that iOS-only symbols are included in the docs.
    "-Xswiftc", "-sdk", "-Xswiftc", sh("xcrun", "--sdk", "iphonesimulator", "--show-sdk-path").strip!,
    "-Xswiftc", "-target", "-Xswiftc", "x86_64-apple-ios#{ios_version}-simulator",
    "-Xswiftc", "-emit-symbol-graph",
    "-Xswiftc", "-emit-symbol-graph-dir",
    "-Xswiftc", ".build")

I updated the plugin to 1.2 to be able to use --include-extended-types now so that we can document our extensions. However, generating symbols fails now:

[207/229] Emitting module RevenueCat
<unknown>:0: error: error opening '.build/RevenueCat.symbols.json' for output: No such file or directory
<unknown>:0: error: error opening '.build/RevenueCat@Dispatch.symbols.json' for output: No such file or directory
<unknown>:0: error: error opening '.build/RevenueCat@SwiftUI.symbols.json' for output: No such file or directory

Checklist

Expected behavior

I expected our swift build command to continue working

Actual behavior

Build fails.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.2.0 Swift Compiler version:

swift-driver version: 1.75.2 Apple Swift version 5.8 (swiftlang-5.8.0.124.2 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0
NachoSoto commented 1 year ago

Actually it appears that was happening because of an invalid reference to SwiftUI in the target. I removed that, and now it seems like I'm close to getting this working. However it seems like I'm missing something in how I'm creating the symbol graph, since this is what I get when calling swift package preview-documentation:

Error: Mixing symbol graph files with and without extension declarations is not supported.

I couldn't find any documentation on this. Do I need a new argument to the swift build call to add extension declarations? I tried -emit-extension-block-symbols (which I found in https://github.com/apple/swift/pull/59047), but that produces the same error again:

[115/229] Emitting module RevenueCat
<unknown>:0: error: error opening '.build/RevenueCat.symbols.json' for output: No such file or directory
<unknown>:0: error: error opening '.build/RevenueCat@Dispatch.symbols.json' for output: No such file or directory
<unknown>:0: error: error opening '.build/RevenueCat@SwiftUI.symbols.json' for output: No such file or directory
abegehr commented 1 year ago

Did you get any further on this, @NachoSoto? For me it's failing on building documentation for my vapor backend using fluent-kit.

NachoSoto commented 1 year ago

Nope, and no word from Apple

yujingaya commented 1 year ago

This seems to be relevant?: https://github.com/apple/swift-docc/pull/715

In the mean time until Swift 5.10, Setting DOCC_EXTRACT_EXTENSION_SYMBOLS to NO worked fine for my project. I don't know about Vapor though.