Does Swift DocC Plugin support iOS frameworks?

Question

Created Jun ’22

Replies 1

Boosts 0

Views 2.2k

Participants 2

I encountered an issue that I could use the SPM DocC plugin to produce documentation.

Will the new version of the Xcode 14 and SPM DocC plugin allow to build directly the documentation using the plugin for the frameworks that e.g. use the UIKit frameworks?

When I try to run the plugin and in addition pass sdk and target parameters

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

More about it on the Swift Forums: https://forums.swift.org/t/swift-docc-plugin-for-swiftpm/54725/30

Currently, I resolve to directly use Swift DocC

rm -rf .build;
mkdir -p .build/symbol-graphs \
  && swift build --target UIEnvironment \
    -Xswiftc "-sdk" \
    -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" \
    -Xswiftc "-target" \
    -Xswiftc "arm64-apple-ios15.4-simulator" \-Xswiftc -emit-symbol-graph \
    -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs;
mkdir -p .build/swift-docc-symbol-graphs \
  && mv .build/symbol-graphs/UIEnvironment* .build/swift-docc-symbol-graphs;
export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render";
rm -rf docs-out;
mkdir -p docs-out/main \
  && ../swift-docc/.build/debug/docc convert Sources/UIEnvironment/Documentation.docc \
  --fallback-display-name UIEnvironment \
  --fallback-bundle-identifier com.plum.UIEnvironment \
  --fallback-bundle-version 1.0.0 \
  --additional-symbol-graph-dir .build/swift-docc-symbol-graphs \
  --transform-for-static-hosting \
  --hosting-base-path /UIEnvironment/main \
  --output-path docs-out/main;
cp -R docs-out/main main

another solution is to use xcodebuild docbuild

Is it an expected shortcoming that cannot be resolved because of the multiplatform nature of SPM or just a temporary limitation?

Boost

Answer 1

Engineer OP

Apple

Jun ’22

Accepted Answer

This sounds like an existing issue being tracked as part of Swift Package Manager here.

I would encourage you to follow-up in that Issue with the SwiftPM folks and mention your use case.

That being said, xcodebuild docbuild is generally what I would recommend for Swift Packages that import UIKit. Xcode 14 includes support for static hosting by default as well as a new setting to configure the DocC Archive Hosting Base Path with DOCC_HOSTING_BASE_PATH. So you should be able to replicate your workflow with something like this which is based on this Xcode documentation:

xcodebuild docbuild -scheme <scheme-name> \
    -derivedDataPath '.build/derived-data/' \
    -destination 'generic/platform=iOS' \
    DOCC_HOSTING_BASE_PATH='/UIEnvironment/main'

find '.build/derived-data' -type d -name '*.doccarchive'

Hopefully this helps!

3