swiftxcodecocoapodsxcodebuildjazzy

Unable to generate doc for test projects using realm/Jazzy

I've been trying to generate documentation for our unit and ui test of a project that has cocoapods. I have created a simple project that is demonstrating my error (pasted below). The link to the project is JazzyTest.

I am using a script to invoke jazzy and when running the script for the app clause everything works as intended and the docs are generated in the JazzyTest/docs folder. However when I attempt to do the same for the JazzyTestTests it fails, while the log says that the build has succeeded (also linked below).

Installed version:

$ jazzy -v
jazzy version: 0.15.1

The steps I am taking are as follows:

  1. clone repo to new directory
  2. cd JazzyTest
  3. pod install
  4. cd ..
  5. ./generateDocs.sh app <- To verify it's all good
  6. ./generateDocs.sh ui <- Problem occurs at this step

Thank you for your time!

xcodebuild target/scheme output:

$ xcodebuild -workspace JazzyTest.xcworkspace -list
Command line invocation:
    /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -workspace JazzyTest.xcworkspace -list

User defaults from command line:
    IDEPackageSupportUseBuiltinSCM = YES

Information about workspace "JazzyTest":
    Schemes:
        CoreBluetoothMock
        CoreBluetoothMock-PrivacyInfo
        JazzyTest
        MSAL
        MSAL-MSAL
        Pods-Apps-JazzyTest
        Pods-Apps-JazzyTest-JazzyTestTests
        Pods-Apps-JazzyTestUITests

Console error:

/Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/executable.rb:39:in `execute_command': /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/bin/sourcekitten ["doc", "--module-name", "JazzyTestTests", "--", "-workspace", "JazzyTest.xcworkspace", "-scheme", "JazzyTest", "-destination\\=platform\\=ios\\ simulator", "name\\=iPad\\ \\(9th\\ generation\\)"] (RuntimeError)

2024-08-01 11:49:38.890 xcodebuild[39479:3252048]  DVTPlugInQuery: Requested but did not find extension point with identifier 'Xcode.InterfaceBuilderBuildSupport.PlatformDefinition'. This is programmer error; code should only request extension points that are defined by itself or its dependencies.

Running xcodebuild

Checking xcodebuild -showBuildSettings

Running xcodebuild

Could not parse compiler arguments from `xcodebuild` output.

Please confirm that `xcodebuild` is building a Swift module.

Saved `xcodebuild` log file: /var/folders/0t/m6b2x0tj5rsfxvr3_3fxvb1m0000gn/T/xcodebuild-F8463AF5-18A0-40E6-844C-148A05D4177E.log

Error: Failed to generate documentation

    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/sourcekitten.rb:229:in `run_sourcekitten'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:83:in `block (2 levels) in build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:81:in `chdir'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:81:in `block in build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:71:in `map'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:71:in `build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/bin/jazzy:16:in `<top (required)>'
    from /Users/user/.rbenv/versions/3.3.1/bin/jazzy:25:in `load'
    from /Users/user/.rbenv/versions/3.3.1/bin/jazzy:25:in `<main>'

Here's a link to the log file

Solution

  • Xcode added a 'Build for Testing' option, this option is key to building the test projects for jazzy to be able to generate the documentation. I had to update build-tool-arguments and add build-for-testing. Once that flag was added jazzy was able to pick up on the test module to generate the documentation for it.

    Additionally, if you use the test flag this will work as well as described in this issue: Generate docs for all modules including testing docs #504, however, this will cause the tests to be executed during the documentation generation.

    So the jazzy invocation went from:

    jazzy \
    --author "Micro-Leads Inc" \
    --author_url https://www.micro-leads.com/ \
    --github_url https://www.github.com/ \
    --min-acl private \
    --build-tool-arguments -workspace,JazzyTest.xcworkspace,-scheme,JazzyTest,-destination='platform=ios simulator' \
    --module JazzyTestTests \
    --output docTests

    to:

    jazzy \
    --author "Micro-Leads Inc" \
    --author_url https://www.micro-leads.com/ \
    --github_url https://www.github.com/ \
    --min-acl private \
    --build-tool-arguments -workspace,JazzyTest.xcworkspace,-scheme,JazzyTest,-destination='platform=ios simulator',build-for-testing \
    --module JazzyTestTests \
    --output docTests