Using @Snippet in SwiftPM for an iOS target

Development Swift-DocC
,
1

I'm trying to use @Snippet inside DocC articles in iOS library target.

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 UIComponents with 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 --build-snippets or --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
reported 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.

Files

Here's the DocC article:

# UI Components

The SDK provides UI components.

Foo

@Snippet(path: "TheModules/Snippets/Bridge/Example1")

Bar

I have 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")
1 Like
2

I also ran into this. It looks like these flags are no longer needed. swift build builds the snippets by default. (I tested this by adding invalid code to a snippet. swift build failed.)

3

Is the posted code accurate? I didn’t see a LeagueModules, which is referenced in the error.

4

I also ran into this. It looks like these flags are no longer needed. swift build builds the snippets by default. (I tested this by adding invalid code to a snippet. swift build failed.)

Thanks! It means it's time to check it again.

Is the posted code accurate? I didn’t see a LeagueModules, which is referenced in the error.

I think it was (it was a long time ago, and I haven't touched it since then). I just provided simplified Package.swift in the post.