Generate different documentation per platform

[kean]

As an author of the frameworks which work on multiple platforms and have slightly different APIs for each one, I would like to be able to generate different sets of documentation for each platform and allow users to select which one they want to see.

As an alternative, it could be the same documentation, but it should clearly indicate which APIs are available on which platforms.

[mattt]

Thanks for writing this up, @kean. I agree that this is something we should do, and it's something I've been thinking about a lot. And when I say "thinking about", I actually mean "dreading". I think this may be one of the hardest problems we'll face, both in terms of programming and design.

A lot of this comes down to a fun aspect of Swift that lets you define conditional compilation blocks pretty much anywhere. You start to appreciate this complexity when you look at what we're doing in SourceFile.Visitor and see how that's manifested in our docs for Alamofire's NetworkReachabilityManager type. (I wouldn't say that our current treatment of this information is all that good).

On the programming side, we'll have to write new functionality to flatten out all of the conditional compilation contexts, collate them by platform and condition, and generate complete symbol graphs for each of the platforms. This will require us to write a parser to make sense of the compilation condition branch expressions.

On the design side, there are a lot of unanswered questions about how best to present this information. Compile different versions of the documentation for each platform, as I think you're suggesting? Put everything together and allow users to filter or toggle between different views? I'd love to hear a few proposals.

[kaishin]

Compile different versions of the documentation for each platform, as I think you're suggesting? Put everything together and allow users to filter or toggle between different views?

I have a hunch that the type of the project will pretty much dictate which of these two is ideal. Projects that vend the same API for all platforms might benefit from a single bundle with a platform toggle for types that need it. Projects that have non-trivial differences between platforms with diverging types might prefer the separate doc bundle approach.

There are also more ways to go about this when using a unified documentation. For instance instead of a toggle per-type, the index page could be a sectioned list of APIs by platform, putting all shared types in a Shared or Common section—not sure if this is technically possible, just spitballing.