I'm trying to use @Snippet inside DocC articles in iOS
I tried many different things (details below), but just for sanity check, when I clone GitHub - apple/swift-markdown: A Swift package for parsing, building, editing, and analyzing Markdown documents. and run the simplest
swift package --build-system xcode --disable-sandbox preview-documentation --target Markdown --port 8081 with Xcode 14.3.1 – it just works.
warning: 'swift-markdown': found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target /Users/dbauke-mac/Projects/swift-markdown/Sources/Markdown/Markdown.docc Building for debugging... Build complete! (0.38s) warning: 'swift-markdown': found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target /Users/dbauke-mac/Projects/swift-markdown/Sources/Markdown/Markdown.docc Building for debugging... Build complete! (0.25s) Input: /Users/dbauke-mac/Projects/swift-markdown/Sources/Markdown/Markdown.docc Template: /Applications/Xcode-14.3.1.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render /Users/dbauke-mac/Projects/swift-markdown/Sources/Markdown/Markdown.docc/Markdown/DoxygenCommands.md:47:3: warning: Topic reference 'DoxygenParam' couldn't be resolved. No local documentation matches this reference. ======================================== Starting Local Preview Server Address: http://localhost:8081/documentation/markdown ======================================== Monitoring /Users/dbauke-mac/Projects/swift-markdown/Sources/Markdown/Markdown.docc for changes...
However, for my iOS package it never finds the correct reference, and both Xcode and CLI complain about an unknown path (Xcode 14 and 15 differ with the message, but I think they mean the same):
.../UIComponents.md:7:1: warning: Topic reference 'LeagueModules/Snippets/Bridge/Example1' couldn't be resolved. No local documentation matches this reference.
I tried multiple different combinations with Xcode 14.3.1, all 15 betas, and the latest toolchain snapshots (5.9 and nightly, selected through
Toolchains in Xcode, but I don't think it worked for CLI, I haven't tried with
xcrun -toolchain yet). I used different combinations of the following:
- Building documentation from Xcode
- Building via
xcodebuild docbuild -scheme UIComponents -derivedDataPath 'docc-derived-data/' -destination 'generic/platform=iOS' DOCC_HOSTING_BASE_PATH='/'
- Building via
swift package -v -Xswiftc "-sdk" -Xswiftc "$(xcrun --sdk iphonesimulator --show-sdk-path)" -Xswiftc "-target" -Xswiftc "arm64-apple-ios13.0-simulator" --build-system xcode --disable-sandbox generate-documentation --target UIComponentswith or without
--build-system xcode(always fails without it), also with or without prefixing it with
/usr/bin/xcrun --sdk macosx.
In CLI I also sometimes get
<unknown>:0: error: unable to load standard library for target 'arm64-apple-ios13.0-simulator' or similar, but I think it's irrelevant, probably some mixed-up state or arguments or so.
I'd be happy to use the solution from DocC Snippets - snippet reference not resolved (use only CLI and
main branch of
swift-docc-plugin), but I think I'm stuck with
xcodebuild or at least
swift package --build-system xcode, but they doesn't seem like working.
I also never managed to make
--enable-experimental-snippet-support working, which would be also important to check snippets correctness. I tried it also with
xcrun --toolchain org.swift.59202308241a, but they both
error: Unknown option '--XXX'
I might have clearly overlook something obvious, and I'm willing to start from scratch, but I'd like to just hear that it should work, and that I should use this or that. There are too many moving parts to test it all.
Here's the DocC article:
# UI Components The SDK provides UI components. Foo @Snippet(path: "TheModules/Snippets/Bridge/Example1") Bar
Package.swift with (added the beginning, as it's pretty big and not open-sourced):
// swift-tools-version:5.8 import PackageDescription let package = Package( name: "TheModules", defaultLocalization: "en", platforms: [ .iOS(.v13), .macOS(.v11), ], products: [ // ...
Snippets/Bridge/Example1.swift is straightforward:
// Example 1 import Foundation print("Example 1")