Cannot generate documentation for targets with spaces in the name

[jballands]

I am currently working on an Xcode project that contains multiple source targets, specifically an iOS target and a WatchKit extension target. I would like to document the code for both targets with Jazzy.

At first, I just ran Jazzy on the Xcode project. From my testing, it appears that Jazzy (or SourceKitten) is picking a target at random and documenting it. So I found the -x switch for Jazzy and used it with the -alltargets flag for xcodebuild; this produced the random target behavior, again.

Looking back on it, it makes more sense to just run Jazzy twice: once for the iOS target and once for the WatchKit extension target. So I ran Jazzy on our iOS target and everything worked fine. Running Jazzy on our WatchKit target, however, produces an error:

$ jazzy -x -target,Summit\\ WatchKit\\ Extension

Running xcodebuild
Could not parse compiler arguments from `xcodebuild` output.
Build settings from command line:
    CODE_SIGN_IDENTITY = 
    CODE_SIGNING_REQUIRED = NO
...
Failed to generate documentation
/usr/local/lib/ruby/gems/2.2.0/gems/jazzy-0.2.2/lib/jazzy/executable.rb:35:in `execute_command': /usr/local/lib/ruby/gems/2.2.0/gems/jazzy-0.2.2/lib/jazzy/SourceKitten/sourcekitten ["doc", "-target", "Summit\\ WatchKit\\ Extension"] (RuntimeError)
...

The iOS target name does not have any spaces in it and works fine. When I remove the spaces from the WatchKit extension target name, everything begins to work:

$ jazzy -x -target,SummitWatchKitExtension

Running xcodebuild
...
building site
jam out ♪♫ to your fresh new docs in `/Users/ajballan/Documents/Work Stuff/Development/raDocs-Live/js/gulp-jazzy/../../gen/auto/apps/summit_1_1_0/jazzy/ios`

[nickygerritsen]

It seems to also be the case for targets with a dash (-) in it.

[jpsim]

You should be able to wrap your arguments in single quotes:

jazzy -x '-target,Summit WatchKit Extension'

[nickygerritsen]

That doesnt seem to work.

My script to create documentation is:

#!/bin/sh

jazzy -m "StreamOne iOS SDK" \
    -a "StreamOne" \
    -u https://streamone.nl \
    -g https://github.com/StreamOneNL/iOS-SDK \
    --github-file-prefix https://github.com/StreamOneNL/iOS-SDK/blob/master \
    --module-version 3.0 \
    -x '-project,StreamOneSDK.xcodeproj,-scheme,StreamOneSDK-iOS' \
    -c

And the output can be found at http://meuk.nickygerritsen.nl/jazzy-output.txt (didn't paste it here because it is really big).

[jpsim]

Thanks for posting the link to that output, I think I know why this is happening.

tl;dr; -m "StreamOne iOS SDK" should actually be -m StreamOneSDK

The longer explanation: jazzy uses SourceKit to extract documentation the same way Xcode does. To do this, it needs to know which compiler arguments are required to build the module. The best way I've found to get the appropriate compiler arguments is to run xcodebuild to build the module, and parse the compiler arguments based on the module name (if passed in). If you pass in the wrong module name, then jazzy can't parse its compiler arguments because no module by that name was built.

[nickygerritsen]

I changed it to StreamOneSDK but that did not seem to do the trick. I've updated the jazzy-output.txt file with the new output...

[jpsim]

could you try disabling incremental builds in Xcode and trying again?

[nickygerritsen]

I'm trying to find this in XCode, but fail to do so :(. Google does not really help, so where can I find this?

[jpsim]

Hmmm, the incremental build really shouldn't be affecting this. Running the following, I can get the compiler arguments:

let path = "/path/to/jazzy-output.txt"
print(parseCompilerArguments(try! NSString(contentsOfFile: path, encoding: NSUTF8StringEncoding), language: .Swift, moduleName: "StreamOneSDK"))

which is what jazzy does to get its compiler arguments. If I had access to the Xcode project I could debug further, but barring that, I don't know what else could be going on here.

[nickygerritsen]

OK I pushed the repo to https://github.com/nickygerritsen/tmp-ios-sdk for the moment being.

Maybe you can find something using that :)

[jpsim]

Ok, you've found a bug in jazzy! I've been able to reproduce this problem and have a proper fix on the way. Here's a temporary fix for you for now:

jazzy -m "StreamOneSDK" \
    -a "StreamOne" \
    -u https://streamone.nl \
    -g https://github.com/StreamOneNL/iOS-SDK \
    --github-file-prefix https://github.com/StreamOneNL/iOS-SDK/blob/master \
    --module-version 3.0 \
    -x '--module-name,StreamOneSDK,-project,StreamOneSDK.xcodeproj,-scheme,StreamOneSDK-iOS' \
    -c

[nickygerritsen]

Great, thanks!

[teodorciuraru]

I need to add:

tl;dr; -m "StreamOne iOS SDK" should actually be -m StreamOneSDK

Whitespaces are replaced with underscores. Words are not concatenated.