Generate-documentation failing on import UIKit

Development Swift-DocC
1

I am trying to test out the new DocC plugin for generating static sites to host via GitHub Pages but I am seemingly getting hung up on something simple.

When I run the generate-documentation command I get failures on UIKit imports....

swift package generate-documentation
Fetching https://github.com/apple/swift-docc-plugin from cache
Fetched https://github.com/apple/swift-docc-plugin (0.52s)
Creating working copy for https://github.com/apple/swift-docc-plugin
Working copy of https://github.com/apple/swift-docc-plugin resolved at main
warning: dependency 'swift-docc-plugin' is not used by any target
warning: dependency 'swift-docc-plugin' is not used by any target
Building for debugging...
/Users/chris/development/tmp/ExampleDocC/Sources/ExampleDocC/ExampleDocC.swift:1:8: error: no such module 'UIKit'
import UIKit
       ^
/Users/chris/development/tmp/ExampleDocC/Sources/ExampleDocC/ExampleDocC.swift:1:8: error: no such module 'UIKit'
import UIKit

Sample project here if you want to give it a shot, I feel like I am just missing something obvious

2

Note that building the DocC documentation requires building the package first. Presumably, swift package generate-documentation functions similarly to swift build in that it only builds for the host platform. (In fact, the former probably calls through to the latter.) Therefore, SPM is trying to build your package on macOS, where UIKit doesn't exist.

In other words, swift build does not build for iOS, (except if you use the Xswiftc flag); therefore, swift package generate-documentation does not work for packages that must be built on iOS.

You'll probably have to use xcodebuild instead for this.

See this thread about the fact that SPM does not support building packages for iOS.

1 Like
3

Also this post does not belong in the development category. This category is about the development of Swift or its core libraries.

4

Then this https://github.com/apple/swift-docc/blob/main/README.md is in need of an update.

The Swift Forums are the best place to get help with Swift-DocC and discuss future plans.

Thanks for the reply I’ll take a closer look.

5

Hi @Chris_Wagner!

I believe @Peter-Schorn is correct here- we don't expect swift package generate-documentation to run successfully if swift build fails since documentation generation depends on being able to build the package itself with SwiftPM.

I'm seeing the same errors from a regular swift build invocation so that seems to be the root cause. (CC: @abertelrud in case I've missed something.)

As a workaround, if you have a recent Xcode 13 beta, you should be able to run something like:

xcodebuild docbuild -scheme ExampleDocC \
    -destination generic/platform=iOS \
    OTHER_DOCC_FLAGS="--transform-for-static-hosting --hosting-base-path <hosting-base-path>" \
    DOCC_OUTPUT_DIR=./docs

to build documentation compatible with GitHub Pages.

1 Like
6

Currently Swift-DocC's only home on the Forums is within the development category so I think this kind of post is acceptable. We can definitely consider adding additional categories for Swift-DocC as the number of posts about Swift-DocC on the forums increases.

4 Likes
7 
xcodebuild docbuild -scheme ExampleDocC \
    -destination generic/platform=iOS \
    OTHER_DOCC_FLAGS="--transform-for-static-hosting --hosting-base-path ExampleDocC" \
    DOCC_OUTPUT_DIR=./docs

That definitely got me further but I'm not sure if it's working to generate a GitHub compatible static site... It outputs a ExampleDocC.doccarchive file in the ./docs directory. I can manually move everything from that to the root of ./docs but that doesn't seem to help and no amount of adjusting --hosting-base-path seems to help either...

This is what I am seeing Documentation

Source: GitHub - cwagdev/ExampleDocC

8

The DOCC_OUTPUT_DIR tells xcodebuild where to output any DocC archives it produces.

Alternatively, you can pass an --output-path directly to the docc executable to achieve what you're looking for here:

xcodebuild docbuild -scheme ExampleDocC \
    -destination generic/platform=iOS \
    OTHER_DOCC_FLAGS="--transform-for-static-hosting --hosting-base-path ExampleDocC --output-path docs"
5 Likes
9

Sorry- I missed this initially. Your documentation is expected to be available at

https://<username>.github.io/<repository-name>/documentation/<target-name>

In this case, it looks like your documentation is already published here:

https://cwagdev.github.io/ExampleDocC/documentation/exampledocc/

2 Likes
10

Ah-ha! Thank you so much, that's working for my actual project now too!

2 Likes