Combined documentation of multiple targets

[taylorswift]

what if we used the scheme to differentiate?

<doc:implicitlyNamespaced> ←→ ``implicitlyNamespaced``
<module:ModuleName/qualified> ←→ ``/ModuleName/qualified``

[ronnqvist (David Rönnqvist)]

Taking a few steps back; the existing syntax for "doc" scheme links in DocC will work for referencing articles and tutorials in external documentation archives by specifying the other archive's identifier like <doc://other-target-identifier/path/to/some/page>. I feel that this is fine and that this initial proposal doesn't need to cover syntax changes for "doc" scheme links. We can always make improvements to the "doc" scheme syntax later when people have been using it to reference external content.

I do however feel that developers should be able to use symbol links to reference symbols in external documentation archives and that this should part of the initial proposal, with a leading slash for external symbol links.

[creativecat (Seth Sandler)]

Any movement on this feature? We're looking for ways to display documentation for all modules in our project.

[ronnqvist (David Rönnqvist)]

Yes, there's an early preview of this feature available to try. I posted more information here:

A preview of DocC's support for combined documentation

Hello, I'm happy to let you know that there's now enough pieces of combined documentation of multiple targets in place across Swift-DocC, Swift-DocC Render, and the Swift-DocC Plugin to enable you to try out an early, and still experimental, version of this feature for the use-case of hosting combined documentation for a Swift package together. I've created a tiny Swift package example that hosts its combined documentation on GitHub Pages as a preview of what's supported today with the latests…

[creativecat (Seth Sandler)]

Thanks. Is this only for the plugin? I couldn't get the plugin to work given we have some objective-c and UIKit code (which is fails on UIKit). So I've been using xcbuild docc as an alternative.

[Joseph_Heck]

The core feature work is in DocC and DocC-Render, so it should be possible to get the symbol graphs from xcodebuild docbuild (or some equivalent process) and then processes them with docc to get the result you're after. docc-plugin, however, doesn't currently have any support for cross-compilation targets (iOS/UIKit in your case, but also applies to Linux) - so the plugin fast-path (swift package generate-documentation) that uses the plugin will only work with code compiling for the host operating system (the OS where you're invoking the command).

[creativecat (Seth Sandler)]

Thanks!

The --enable-experimental-combined-documentation doesn't seem to be available outside of the plugin. Or do I need to use the version from the repo?

I've been having a hard time finding overall documentation for what the flags are for both the plugin and docbuild to know what's available or what the right values could be.

[Joseph_Heck]

There's very minimal documentation on this feature as yet - this thread being most of the detail. The flag is on the plugin, at least available in version 1.4.3 of the plugin.

The flags for the plugin aren't well exposed yet either, but since they're all argument parser based, you can at least use swift package generate-documentation --help and swift package preview-documentation --help to see what's available directly. docbuild is a different story since it's entirely within Xcode and closed-source, so Apple's docs are all we have there.