Are there updates on using Swift-DocC with multiple targets?

[nmgswift]

I noticed that this has been talked about in both of the following threads:

Use cases for combined documentation of multiple targets in Swift-DocC

Hello everyone. I would like kick off a discussion about linking between documentation for multiple targets and hosting documentation for multiple targets together. As a first step I would like to focus the discussion on goals and use cases. Two example use cases that we aim to solve are: A team with two apps and a shared framework should be able to write documentation links from each app to the framework but not between the apps or from the framework to either of the apps (more on this later…

Combined documentation of multiple targets

Hi. This is a continuation of this topic which focused on goals and use cases for combined documentation of multiple targets. In this new topic I'd like to focus on the technical aspects of how to build combined documentation for multiple targets and find a high level design with the right tradeoffs to support the goals and use cases from the previous thread. An example from many combined use cases The "sloth" development team is working on a Swift package that contains 4 libraries; "A", "B", …

However, the latest reply (out of both threads) is September 2023. Are there any updates on these use cases? Are they able to be used currently, or not?

[ronnqvist (David Rönnqvist)]

Yes. There has been a significant progress on building out support for both linking between documentation for multiple targets and hosting documentation for multiple targets together.

The two main reason for not posting an update in the forums yet is that the experience was rather limited until most of the pieces was in place and that it required running multiple commands in a script to build a combined documentation archive with links between targets.

Render combined navigation for merged documentation archives by mportiz08 · Pull Request #877 · swiftlang/swift-docc-render · GitHub will address one of the last limitations to a early, initial experience and Add initial experimental support for combined documentation for multiple targets by d-ronnqvist · Pull Request #84 · swiftlang/swift-docc-plugin · GitHub will make it convenient to build a combined documentation archive with links between targets.

I'll post a real update in the forums when both those pieces have landed, which will make it the first early version that's usable end-to-end and that solves some of the most common use cases.

[JaanusK (Jaanus Kase)]

Oh this is great to know, thank you.

I see that the first one is merged already.

Should I be able to use your branch of the plugin now, or does it require some special toolchain? I didn’t try yet, but I might soon.

[ronnqvist (David Rönnqvist)]

You can use that branch of the plugin with the Xcode 16 betas. The plugin will warn and exit if the toolchain doesn’t support the necessary features.

[nmgswift]

@ronnqvist

It looks like both of the branches you mentioned have been merged. Do you have an estimate on when they will they be landing in Swift?

Thanks!

EDIT: It looks like it's based on the plugin. Is there documentation on how to use the flag specifically?

EDIT (again): OK, I've played around with it and it seems the single target case for previews stops me from being able to link between my targets.

[ronnqvist (David Rönnqvist)]

@nmgswift

It looks like both of the branches you mentioned have been merged. Do you have an estimate on when they will they be landing in Swift?

The initial Swift-DocC and Swift-DocC Render changes are already available in recent Swift 6.0 toolchains.

Additionally, as we were working on this and using it we realized that we also wanted to land Synthesize a minimal landing page for combined archives by d-ronnqvist · Pull Request #1011 · swiftlang/swift-docc · GitHub for as an important enhancement and Support `--output-path` when building documentation for multiple targets. by d-ronnqvist · Pull Request #89 · swiftlang/swift-docc-plugin · GitHub as a quality-of-life improvement.

The former is available in recent Swift development toolchains and all Swift-DocC Plugin changes are available in the 1.4.x release.

With those changes, we feel like there's enough pieces in place for people to try out an early preview of what's currently available. I made a separate post about this just now.

@nmgswift

EDIT: It looks like it's based on the plugin. Is there documentation on how to use the flag specifically?

Because there may still be breaking changes we've not updated the main package documentation to cover this yet. However, the plugin 1.4 release notes and the other forums thread from just now both show minimal examples of using the new flag.

In short, it should just be "build some number of targets/products" and pass the --enable-experimental-combined-documentation flag. You don't need to pass any extra feature flags to DocC. The plugin takes care of that.

[JaanusK (Jaanus Kase)]

Yay. I am here to report some success.

Now that everything is merged, I can just use the swift-docc-plugin 1.4.0 or greater in my package, and use the --enable-experimental-combined-documentation to generate some basic combined documentation for my packages as expected. Cross-module links appear to work fine.