Allow combined documentation of multiple targets

[ffried]

Feature Request: Allow combined documentation of multiple targets

Description:

Transferred from swiftlang/swift-docc-plugin#12 (comment).

Allow generating the documentation for multiple targets into one bundle, to make it easier to host the documentation for multi-target packages in a central place.

Motivation:

Currently, docc only supports generating the documentation for one target at at time. Generating documentations for multiple targets results in separate documentation bundles. This makes it hard to host the documentation for a package that contains multiple targets.

For example our color-components package has multiple targets, which makes hosting its documentation in a central place a bit complicated.

Importance:

It's not uncommon to have packages with multiple targets. Apple's own SwiftNIO has many targets and (almost) all of them have documentation. However, with docc it's currently hard to generate and host this documentation in a central place (like GitHub Pages).
With a bit of trickery, it's possible to merge the documentation pages together, but it's far from optimal.

Alternatives Considered:

Manually develop an 'index' page which links to sub-pages containing the documentation of each target separately. This would require quite a bit of work to have a great "look and feel" so that the index page looks similar to the documentation pages.

[ffried]

With a bit of trickery, it's possible to merge the documentation pages together, but it's far from optimal.

We've actually done this for our packages with this GitHub Actions workflow.
It generates the documentation for all targets, merges them together (since currently it's essentially only data/documentation/${TargetName} and documentation/${TargetName} that differs and those folders can easily be placed next to each other. The only thing that cannot easily be merged is the metadata.json in the root of the bundle.

We then also generate an index page that lists all targets. No style whatsoever, though.

Update: The workflow above simply references an "internal" shared workflow now. Except for now being configurable, it still does the same as originally described.

[lukepistrol]

This would be an awesome option!

[d-ronnqvist]

This will require design discussions on several topics, both to determine what use-cases to prioritize and to determine how this fits into other tools and workflows and if any new configuration needs to be surfaced and how.

[amyworrall]

+1 for this, although I can see how it would need careful design consideration!

[d-ronnqvist]

We've been having some discussions about this and would like the community's feedback. I've created this topic in the Swift Forums to talk about goals and use cases so that upcoming discussions in the forums can focus on solving the right problems.

[pylapp]

Is there any news about this feature?

In fact in the OUDS project we define a Swift Package with, today, up to 9 targets (according to the Package.swift.
Until now our product is dedicated only to iPhones and iPads.

We did not succeed in building automatically the documentation for the 9 targets, and have them all merged in one file bundle of HTML, CSS and JS files.

The only workaround we have is to build the documentation with Xcode manualy to get the 9 catalogs, then export them in 9 doccarchives, so as to make some tinkering with their content. But it is not efficient at all sadly. And in a near future the repistory won't contain any app anymore as it will be moved elsewhere, thus we will have only a "pure" Swift Package repository.

[d-ronnqvist]

The most recent news about this feature is in this Swift Forums thread.

[pylapp]

FYI, if someone here needs some command to build documentation for static website for a Swift package containing several targets, here is a working command in my side:

# Where DOCUMENTATION_HTML_LOCATION is a path

swift package \
    --allow-writing-to-directory "$DOCUMENTATION_HTML_LOCATION" \
    generate-documentation \
    --enable-experimental-combined-documentation \
    --target target1 \
    --target target2 \
    ...
    --target targetN \
    --output-path "$DOCUMENTATION_HTML_LOCATION" \
    --transform-for-static-hosting

In addition we needed to add .macOS(.v13) in the Package.swift products (because of our API in use in our codebase), and we needed also to use build-time conditional imports of UIKit (not avaialble with swift package).

I gathered our intel here: Orange-OpenSource/ouds-ios#626

Hope it will help people, anyway, thank you for the tool!