What's the sane way to produce multi-target package documentation?

Development Swift-DocC
1

I’m still struggling with this a lot. I find myself in what I deem a common situation, which is a SwiftPM package with multiple targets, e.g.:

  • UmbrellaTarget
    • FirstTarget
    • SecondTarget
    • ThirdTarget

The umbrella target has @_exported imports of First/Second/ThirdTarget, but I can avoid this with an #if clause if this hinders the documentation build process.

I’m trying to produce the package documentation with both swift-docc and xcodebuild, and I hit different blockers:

  • swift-docc: Fine overall, but there is this bug, which I reported months ago, and it seems unlikely to be fixed soon.
  • xcodebuild: The “Build Documentation” works well initially, and produces packages for each target. However, the exported-imported entities from the sub-targets appear in the umbrella target docs hierarchy, but are undocumented. Also, I cannot cross-link from Swift code, as in /FirstTarget/SomeEntity.

Any hint is truly appreciated.

Thanks!

2 Likes
2

Just wanted to add that the swift-docc option has the best outcome so far, and maybe also acceptable for production. It only makes me give up on the cross-links in the /// comments, which is no big deal in hindsight.

In fact, this is often my scenario:

  • SomeProtocol in target A
  • SomeClass implementing SomeProtocol in target B, depending on A
  • The link to SomeProtocol in the SomeClass documentation appears broken

Nevertheless, I realized that the "Conforms To" link to SomeProtocol at the bottom of SomeClass is resolved correctly, and all in all, it's enough.