Add support for Apple .doccarchive

[luispadron]

Summary

Closes #1420

This adds support for building .doccarchive for rules_apple targets. It uses the symbol_graph feature from rules_swift to collect the symbol graph. It then invokes xcrun to find docc and create the .doccarchive.

Example:

docc_archive(
    name = "HelloWorldSwift.doccarchive",
    dep = ":HelloWorldSwift",
    fallback_bundle_identifier = "com.example.hello-world-swift",
    fallback_bundle_version = "1.0.0",
    fallback_display_name = "HelloWorldSwift",
)

Build it:

bazel build //examples/ios/HelloWorldSwift:HelloWorldSwift.doccarchive
xed  bazel-bin/examples/ios/HelloWorldSwift/HelloWorldSwift.doccarchive

Preview the docs:

bazel run //examples/ios/HelloWorldSwift:HelloWorldSwift.doccarchive

Tasks

• Support ios_*_framework, ios_application like bundling rules.
• Use transition for enabling symbol graph outputs.
• Determine if Info.plist needs to be provided / copied.
• Add support for including any .docc bundles defined in data.
• Tests
• Documentation

[louwers]

This is awesome!

Objective-C support would be highly appreciated.

[luispadron]

Objective-C support would be highly appreciated.

I think we'd need to follow what @keith mentioned in #1420 and use the flag in: https://forums.swift.org/t/clang-support-for-objective-c-symbol-graph-generation/57689/4.

It's possible we could transition on that flag in this rule as well, but not sure if we need to add more details to some objective-c provider somewhere to pass along the symbol graph directory.

If anyone has more details let me know! Working through Swift support since it probably addresses most use cases and worst case we follow up with Objective-C support

[luispadron]

I'm also wondering if we need to create two rules one for the .docc bundle and another for .doccarchive?

Maybe. It might not be required if the docc_archive handles the internal .docc for the target. We still might want a docc_bundle rule similar to apple_resource_bundle, but since this would be its own target it would have no attached symbol_graph so doubt it would provide too much value to build that on it's own.

[luispadron]

Updated the PR! What I have is good enough to get existing swift_library, ios_application, etc building valid .doccarchives for their srcs 🎉

I've updated the tasks with some next steps I think I need to address, if you have thoughts on design so far please let me know!

[jerrymarino]

@luispadron this is great, thanks so much for adding it. Really excited to pull it down and give it a whirl 🚀

It seems like we'll need some Xcode bits to get it working in the GUI in addition to this?

[luispadron]

It seems like we'll need some Xcode bits to get it working in the GUI in addition to this?

I'll open a separate issue in rules_xcodeproj for .docc build support but with the rule in this PR: bazel build <target> && xed <target_output_path> will add the archive to the Documentation window in Xcode which is essentially what Build for Documentation does.

[luispadron]

This is probably ready for an initial pass! I'll add tests and docs after any changes from that.

The HelloWorldSwift example showcases some simple symbol graph + .docc bundle support. Try both build and run!

[BalestraPatrick]

LGTM overall!

[BalestraPatrick]

@luispadron If you fix the buildifier errors and regenerate the docs we should be good to go.

[louwers]

The (lack of) Objective-C support should be documented.

[luispadron]

@luispadron If you fix the buildifier errors and regenerate the docs we should be good to go.

@BalestraPatrick Thanks for the review! I'm going to add some tests before I un-draft it this month and update documentation.

@louwers I'd love to add Objective-C support, I'll see if I can spend time looking at it more, if not will update docs to note as such.

[luispadron]

Added tests and documentation, think this is ready for initial support for .doccarchive once we get enough reviews.

[brentleyjones]

@jpsim I know you had interest in this before. Pinging for visibility.

[BalestraPatrick]

I wonder if need private_deps here too

[BalestraPatrick]

I assume this is likely expected (we do the same with some other Xcode tools IIRC), but do you remember what exactly was the error in this particular situation?

[luispadron]

I dont have the exact error but essentially the .docc bundle was missing from the sandbox so it would fail along the lines of "bundle not found"

[jpsim]

Thanks for adding this, @luispadron 🙏