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.