Generate docs for all modules including testing docs

[smac89]

I have 3 modules in my project, the main one, unit tests, and ui tests. How do I specify that I want all the modules generated at once?

[jpsim]

Jazzy generates docs on a per-module basis, with no easy command-line way to merge docs from multiple modules. You could look at how podspec_documenter.rb does this and re-expose that functionality as a command-line option though.

[oscarmk1]

How can you build the Unit tests module?, I have only been able to build my main project module, trying to build other modules gives me an error.

[smac89]

@oscarmk1
Supposing you have given the Unit tests module a name, you can supply this as an option in .jazzy.yaml as module_name: NameOfModule or command line option --module NameOfModule

[oscarmk1]

@smac89
Thank you, that's is what I have tried, but it gives me an error, I created a brand new single view application named TestDocGen, with unit tests enabled, which gives the "Product Module Name" a name, this is what I get, is there anything else that you are doing to get it to work?:

$ jazzy --module TestDocGenTests
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/cw/c3xfrymx0zdd__gtkr9z3ng9ljhgnv/T/xcodebuild-BFEB949E-3DF0-47F9-A716-54849E23A400.log
Failed to generate documentation
/Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/executable.rb:36:in `execute_command': /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/SourceKitten/bin/sourcekitten "doc", "--module-name", "TestDocGenTests"

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/cw/c3xfrymx0zdd__gtkr9z3ng9ljhgnv/T/xcodebuild-BFEB949E-3DF0-47F9-A716-54849E23A400.log

Failed to generate documentation
from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/sourcekitten.rb:140:in run_sourcekitten' from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:57:inblock in build'
from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:in chdir' from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:inbuild'
from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/bin/jazzy:15:in <top (required)>' from /usr/local/bin/jazzy:23:inload'
from /usr/local/bin/jazzy:23:in <main>'

I am using jazzy version: 0.5.0

[smac89]

You can try specifying the swift version as well. I have version 2.2 and jazzy was initially expecting 2.1, so I had to do swift_version: '2.2' in my .jazzy.yaml file

[oscarmk1]

@smac89 Thanks, I tried it like this:
jazzy --swift-version 2.1.1 --module TestDocGenTests

xcrun swift -version is Apple Swift version 2.1.1 (swiftlang-700.1.101.15 clang-700.1.81)

But I am getting the same error. What jazzy and XCode version are you using?

[jpsim]

Unfortunately, Xcode or xcodebuild doesn't really let you build a test bundle without running it. You'll have to pass -x test to your jazzy arguments, which will be forwarded to xcodebuild.

[oscarmk1]

@jpsim Thanks that worked!, had to pass a couple other arguments too but it works nicely.

[jpsim]

Glad to hear it! Maybe you can pass the full command you ended up with so that @smac89 and others can benefit from your work? Thanks!

[oscarmk1]

@jpsim Sure, this is what I am using to build the test module only:

jazzy --min-acl internal --swift-version 2.1.1 --module MyTestModule --xcodebuild-arguments test,-scheme,MyScheme,-destination,id=4923F912-1D0B-4188-B0A4-5C1B12B41FF,-workspace,MyWorkspace.xcworkspace,SYMROOT=$(PWD)/build 

I am using cocoapods, and therefore I am providing the workspace, so just remove that part if using a regular project. The SYMROOT I found it to be required or else it won't link properly during compilation when using cocoapods. The destination id is the id of your simulator instance, and it will be different than that one, you can also provide a platform and OS version, but for some reason I could not get it to work by passing the paremeters to xcodebuild using jazzy, it would work with xcodebuild by itself, so I think I was just using the wrong format.

[jpsim]

Thanks for sharing!

[cpatterson-lilly]

For completeness, here is a sample .yaml file that also works for generating unit test docs written in swift 3.1:

{
    "min_acl": "internal",
    "output": "docs/tests",
    "objc": false,
    "clean": true,
    "module": "<MyTarget>Tests",
    "use_safe_filenames": true,
    "theme": "fullwidth",
    "swift_version": "3.1",
    "xcodebuild_arguments": [
        "test",
        "-scheme", "<MyTarget>",
        "-destination", "platform=iOS\ Simulator,name=iPhone\ 7"
    ]
}

Replace <MyTarget> with the name of your main build target. This assumes your unit test target is named "<MyTarget>Tests". If not, edit the "module" setting appropriately.

Note the syntax for the -destination parameter; you need to escape the embedded spaces in the platform and name values, and delimit them with a single comma (no spaces after the comma).

Hope this helps someone!

[reitzig]

Thought: If we have to run the tests, anyway, why not aggregate the results in the Jazzy output as well? That way, we'd have a nice test report as well!

Scripting it, I'd insert placeholders in the test documentation, extract the test result from whatever is dumped on the CLI, and then search-replace the HTML. Of course, it'd be much more convenient if Jazzy did this, and I'd expect it to be easier and cleaner as well, seeing as Jazzy knows about all the symbols, anyway.

Worth a ticket?

[johnfairh]

I've found if you use xcodebuild action build-for-testing instead of test then jazzy works fine and produces docs for the test module without running any tests.

If that doesn't work for you then Xcode 9 has also added -skip-testing: and -only-testing: options to xcodebuild (do check their syntax in the man page).

Doing -skip-testing:MyProject-iOS\ Tests to skip everything doesn't quite work because xcodebuild fails complaining there is nothing to test!

But -only-testing:MyProject-iOS\ Tests/TestClass1/testAQuickThing does work as expected, fully builds the test bundle and runs just the one test.