Others have already chimed in about the usual package author cases but I'll add more examples:
Cross-library (cross-package) links
This is the "A target’s documentation should be able to link to that target's dependencies' documentation" case you mention.
However I'd like to give a few more concrete examples as well as how we'd want to use these.
So libraries which use e.g. Logging
(GitHub - apple/swift-log: A Logging API for Swift) would want to be able to link to them like:
``Logging/Logger``
However, not every single library using logging should replicate the logging docs (!), that's bad for SEO, instead they should link to "wherever the logger docs are hosted".
docc by itself can't know where to link to, as it depends where other libraries deploy/host their documentation. Most will do so on github pages or on packageindex.com (like so RevenueCat Documentation – Swift Package Index random example).
We will need to configure the baseURL for links to be formed, therefore I suggest a mapping file like this:
Side note: Preferably this would be configured in the SwiftPM plugin via a nice type-safe configuration, but we're lacking this feature still in SwiftPM, so for now let's go with an external configuration file.
We'd need to configure "when trying to link docs of Logging (which we know is from package swift-log), use this base url", so a mapping file could look something like this (details open to discussion of course):
doccHostingLocations:
// defaultBaseURL: "..." // could be set optionally if most follow some pattern
packages:
- name: swift-distributed-actors
baseURL: "https://apple.github.io/swift-distributed-actors/$VERSION/documentation/$TARGET"
- name: swift-log
baseURL: "https://apple.github.io/swift-log/$VERSION/documentation/$TARGET"
- name: swift-metrics
baseURL: "https://apple.github.io/swift-metrics/docs/$VERSION/documentation/$TARGET"
- name: mqtt-nio
baseURL: "https://swiftpackageindex.com/swift-server-community/mqtt-nio/main/documentation/$TARGET"
Note the mqtt-nio example didn't support $VERSION
since it only hosts main
version for now... Other projects in my example do host docs for specific versions though, so that's why the baseURLs contain $VERSION. As we build docc documentation, we know what versions we depend on and create well-formed links to the exact versions MY project is depending on.
There could be fallbackURL
as well, if $VERSION was not published, we could link check them and offer the fallback link but that's future work...
This allows us to strive in an ecosystem regardless where documentation ends up hosted. It could be all on github pages, or all on the package index, or on my website because I happen to own a company that also has swift APIs and want to host it on my site for whatever reason.
Prior art:
This is how it is solved in scaladoc, by e.g. the GitHub - ThoughtWorksInc/sbt-api-mappings: An Sbt plugin that fills apiMappings for common Scala libraries. sbt plugin.
Other examples:
Multiple target single-package documentation
This is the "Developers should be able to host multiple related targets in a single documentation archive." case, and I'd just like to give some examples:
Projects like NIO or swift-distributed-actors have their functionality split across many modules. For example:
are all the same package, and very often need to cross link between eachother; e.g. A ChannelPipeline
documented in NIOHTTP1
needs to refer to NIOCore's EventLoopFuture
https://apple.github.io/swift-nio/docs/current/NIOHTTP1/Extensions/ChannelPipeline.html#/s:7NIOCore15ChannelPipelineC8NIOHTTP1E21addHTTPClientHandlers8position21leftOverBytesStrategyAA15EventLoopFutureCyytGAC8PositionO_AD018RemoveAfterUpgradeL0OtF
Such links should work, and they are all hosted in the same place.
Prior art
In a previous life, during my Akka work, we solved this using a build plugin we developed called "unidoc" which collapsed all docs from many modules into a single docs page. Just for reference: GitHub - sbt/sbt-unidoc: sbt plugin to create a unified Scaladoc or Javadoc API document across multiple subprojects.
docc likely can do better than that here, and host them still separately, but know how to link between the targets/modules.
Re: Documentation archives should not contain known broken links
Links to documentation in other targets are only valid if both are hosted next to each other or if both are hosted together. Developers should have the ability to remove links to targets that won’t be hosted together.
This one I wanted to understand better... I agree that dead links are bad, but I would like to make sure that this is an option and not the only way. We definitely want to link across packages (see the first writeup in my post here).
I believe what this also means is that while we build documentation together, we can therefore issue warnings for bad symbol links to a dependency; once that has been built, we can assume the documentation of the dependency at the same version we built against, will be valid at the published url (that we point at with the baseURL
).
"Landing page" for docs
You hint at it somewhat but it wasn't explicitly stated so I'd like to ask:
Generally when "hosting many documentation of many, related, modules" we'd want to have a landing page for such pages. In the sense of "Welcome to MyLibrary! This library does..." which is not strictly part of documentation of any specific target, but an overall documentation of the package. Which then goes on and links into specific targets.
This may be is a separate feature to talk about, but having to designate one of the targets "as the main one" in order to put the landing page in there is a bit weird and I'd love to improve upon this.
--
Hope these help and I'm really looking forward to all the great docs ecosystem we can get started building using these improvements