Combined documentation of multiple targets

[theMomax (Max Obermeier)]

Hi!

Very nice proposal, David! I definitely agree that making separate calls to docc convert should prove to be way more convenient for manual usage but especially when integrating these features into the SPM DocC plugin and IDEs. I also think that we should spend significant time on those to make usage of cross target documentation as easy and convenient as possible.

I'm not 100% sure if I understood your explanation of the merge command correctly. When passing only pre-built documentation archives to the command, those would all be hosted next to each other - independently of their dependency hierarchy - as direct children of documentation, correct?

However, what do you mean by this?

@ronnqvist

If a documentation catalog is passed, the developer is responsible for linking to each target and/or tutorial as they see fit. The merge action’s documentation catalog can link to documentation from all its input documentation archives (same as convert action dependencies).

Would all pages from the pre-built documentation archives still be present at the same paths as compared to when there is not documentation catalog passed to the command? Or would the new archive only include those pages that are (transitively) linked to from the new documentation catalog? I guess the "target" corresponding to the new documentation catalog would also be hosted next to the targets from the pre-built archives, wouldn't it?

I also agree with the leading slash syntax as a shorthand for absolute links.

@ronnqvist

As a more convenient way to link to other target's documentation, I propose that the existing symbol link syntax be extended with a leading slash for links to symbols in other targets. A leading slash for links to symbols in the current target would be optional but supported. For example, to link to the "something" property of "SomeClass" in "SomeDependency" from the documentation for "MyTarget", I would write:

``/SomeDependency/SomeClass/something``

If "MyTarget" have a symbol also named "SomeDependency" I would like to it with:

``SomeDependency``

However, I think it would be beneficial to also allow (sufficiently qualified, i.e. starting with a target name) relative links to be used for referring to pages from other targets. This results in relative links behaving just like Swift code, where a local extension to external types can shadow the original member. This point already came up in my proposal-discussion on how to Document Extensions to External Types Using DocC :

@theMomax

Once [SR-15431] Support DocC references to symbols defined in another module - Swift is implemented, we always follow a local first strategy. I.e. if a module shadows a symbol, the simple EXTENDED_MODULE_NAME/SYMBOL_PATH identifier links to the local page of the extension (hostpath/EXTENDING_MODULE_NAME/EXTENDED_MODULE_NAME/SYMBOL_PATH), not to the original page in the extended module's documentation catalogue (hostpath/EXTENDED_MODULE_NAME/SYMBOL_PATH).

In order to reference shadowed symbols, one must use absolute identifiers. Absolute identifiers are basically the URL without the leading hostpath. That is, shadowed symbols can be referenced unambiguously using /EXTENDED_MODULE_NAME/SYMBOL_PATH (note the leading slash).

Firstly, note that absolute identifiers are always an option, i.e. one could also refer to SlothCreator's NameGenerator in the Sloth Creator documentation catalogue using /SlothCreator/NameGenerator.

Secondly, relative identifiers can be used for referencing external symbols, if they are not shadowed. That is, Swift/Array/count is a valid identifier in the SlothCreator module, even though there is no local extension that defines a count on Swift.Array.

Just for completeness: my PR from the extension topic already brings support for absolute symbol links in Swift-DocC: https://github.com/apple/swift-docc/pull/335.

@taylorswift

Biome uses leading slash to denote package namespace, eg:

``/swift-nio/NIOCore/ByteBuffer.readableBytes``

this syntax also provides a convenient place for a version tag:

``/swift-nio/2.40/NIOCore/ByteBuffer.readableBytes``

Biome has dependency-aware symbollinks so bare-module references don’t require prefixing, you can just refer to them like:

``NIOCore/ByteBuffer.readableBytes``

as you do in source.

at some point i want to see Biome be able to reference a branch name:

``/swift-nio/async/NIOCore/EventLoopFuture``

this will be hard to do if leading slash denotes module namespace, because unlike version numbers, branch names look like module names. so i urge you not to burn leading slash on module name.

I don't think linking to two different versions or even branches of the same target is a very common requirement, however, one could also solve this problem by embedding the version/branch name in the target name. This could be done in the configuration file proposed in the use-case thread like this:

    - name: Logging
      baseURL: "https://apple.github.io/swift-log/current/documentation/Logging"
    - name: Logging_1_3_0
      baseURL: "https://apple.github.io/swift-log/v1.3.0/documentation/Logging"
    - name: Logging_main
      baseURL: "https://apple.github.io/swift-log/main/documentation/Logging"

Solving this on a target level could make sense since we're already building documentation on a per-target (not per-package) basis.