Combine Generated Documentation

[gngrwzrd-intel]

This is probably a crazy request.

It would be nice if you could combine documentation together from different projects.

I'm working on a project where each group is building an SDK and documenting it. Unfortunately they're all in separate repositories, so even though the SDKs are related and really should have documentation all in one place, they end up having separate documentation for each SDK.

It would be awesome if there was some intermediate format so you could generate documentation for frameworkA, and then generate docs for frameworkB and combine that with frameworkA documentation.

Or maybe there's a separate switch to the jazzy command to combine documentation files where it simply updates the generated HTML files by combining them?

[jpsim]

This isn't crazy at all, in fact, it's how CocoaPods support works today, by building all the support platforms & subspecs, then merging them together. You can homebrew this yourself today by running sourcekitten doc on all the things you want to document, then merge the JSON output somehow, then feed that to jazzy's --sourcekitten-sourcefile parameter.

There's no conveniences to do this in a single jazzy command today though.

[gngrwzrd-intel]

@jpsim That's perfect. Thanks!

[AnthonyOliveri]

For anyone wondering how to implement @jpsim's suggestion, here is a simple example of how to combine API docs for a framework and one of its Cocoapods dependencies using bash.

dependencyDocs=$(sourcekitten doc --module-name MyDependency -- -project Pods/Pods.xcodeproj)
frameworkDocs=$(sourcekitten doc)
echo ${dependencyDocs%?}', '${frameworkDocs:1} > kitty.json
jazzy --sourcekitten-sourcefile kitty.json

[dabrahams]

I have a project in a single repo, but it's built from multiple modules, and until this has first-class support in Jazzy I'm afraid I'm forced to use Apple's DocC tool (whose support for merged documentation is not great either, but is a start).

[dabrahams]

I take it back; DocC can't merge documentation from my multiple modules. @AnthonyOliveri is there an incantation similar to this one I can use to merge the output of multiple jazzy invocations?

Thanks!

[AnthonyOliveri]

I take it back; DocC can't merge documentation from my multiple modules. @AnthonyOliveri is there an incantation similar to this one I can use to merge the output of multiple jazzy invocations?

Thanks!

You want to merge multiple HTML outputs from jazzy? If so, it certainly wouldn’t be as easy as my original suggestion for merging JSON. It’s better to find a way to start with generating raw docs with sourcekitten on each module first, then use jazzy just once at the end of the documentation-generating process.

[johnfairh]

Some SPM merge-module instructions it's worth linking directly from this issue here.

Jazzy itself doesn't understand multiple modules per docset, which means that when you do this, the docs don't show what module a thing comes from, cross-module extensions are not clear, and types that share names in separate modules get merged (or worse).

[johnfairh]

Native support for merging multiple modules in master via #1379.

[jpsim]

Nice, thanks @johnfairh !