Documentation (Tools) Workgroup Meeting - 1 December 2025

Swift Documentation Tooling Workgroup Updates
1

Documentation Workgroup Meeting 1 Dec 2025

Attendees

  • Franklink Schrans
  • Sofia Rodriquez Morales
  • Vera Mitchell
  • David Ronnqvist
  • Sven Schmidt

Topics

Joe: @Availability for platforms without ABI versions
Franklin: testing experimental DocC in SPI earlier

Discussion

Franklin: Since Kyle Murray, who worked on Swift Programming Language Book work and supported it as part of this workgroup left, we haven't really talked at all about TSPL in this group. The Ecosystem steering group is asking about changing this workgroups name from "Documentation" Workgroup to "Documentation Tooling" working group.

Vera: I guess discussion of TSPL topics, etc - would go to ecosystem steering group?

Joe: I'm good with the rename - the docs proposal from the Core Team matches up with this request, with reviewers coming from the various steering groups - so TSPL lines up well with the language steering group.

Joe: Using 0.0.0 to indicate platform-only, no version

Sofia: Symbol from C already has some of this pattern. DocC render does something akin to this today.

Joe: Missed where this was happening

David: Info.plist allows you to specific platform without a version that applies to all symbols. But that would make sense to apply to directives as well.

Vera: That tracks - you can specify there to mask out an availability.

Joe: Unavailability? Magic string in Info.plist

Sofia: There's a string you can add into the Info.plist to layer over symbols without. Symbol data is always considered a source of truth, and no overridden.

David: Everything in Info.plist is applied globally, not to individual symbols. Would be good to have that capability for specific symbols.

Joe: The inciting asks for this partially came out of swift-testing, where they have some symbols that are specific to only a single platform (windows), or a few platforms.

David: To make a symbol unavailble for non-windows platforms, swift-testing example, you'd annotate in source with the @unavailable for each of the various platforms to
mark it off.

Franklin: Wanted to talk more about preview runs for DocC experimental features.

Sven: We do some previews after WWDC - we've built from various nightlies in the past. We do have the capability, and have done this in the past, to install the beta. Would depend a bit on what we're trying to test and when. Testing on Linux is very simple. The stuff that's complicated is macOS toolchains that need installation on doc builders.

Franklin: There are ways to override the version of DocC. They way you build is trhough the plugin today?

Sven: Yes - although when using Xcode to build, it's the Xcode toolchain that specifies it all. The Xcode build documentation has two steps. The SwiftPM variation is easier - it's a single step leveraging the plugin.

Franklin: So there's two paths here - one through docbuild and the other through the package plugin.

Sven: Yes, exactly - for packages that need/want iOS, we have to use docbuild to generate the documentation.

Sven: The more we can target the testing to a single platform, the easier it gets. The way we've done this in the past is setting up a separate builder in staging, and upgrade just that system to do the building. Only have support for a single builder setup in each environment.

Franklin: One thing that might make this easier, it might be able to leverage just a different DocC executable.

Sven: That doesn't actually make this easier for macOS, since we only have images and control of the images at a high level, not aat env. level.

Sven: Our images are technically public, so linux is a bit easier if possible. Anyone could pull the image and give it a shot.

Sven: This is out images repository: finestructure / spi-images · GitLab - base are the linux builds, and you'll see variants that are used for specific platforms, etc. Modify the doc-file base and have a variant that uses the DocC executable that we want to test.
Sven: We can also specify this by package as well, in the SPI.yml you can specify a dockerfile, so we could allow-list it and then any package could experiment/explore with the new builder image.

Sven: The documentation for aiming a package at a specific linux docker image: https://swiftpackageindex.com/swiftpackageindex/spimanifest/1.11.0/documentation/spimanifest/commonusecases#Images-for-Linux

David: Did we have a specific package in mind to use as a test case.

Franklin: We'd talked in previous chats about using Swift OpenAPI runtime: https://swiftpackageindex.com/apple/swift-openapi-runtime

Joe: Wanted to let everyone know I was continuing to set up the end to end testing GitHub - heckj/example-docc-project: An example Swift package set up for hosting documentation now has a playwright test. I'm still adding content to it - nothing meaningful, but the idea being a collection that shows all the various features that visibly show up in documentation - right now it has a article-only module and a module with symbols, being generated as combined documentation.

Joe: I've also made up GitHub - heckj/DocCArchive that can read in and parse through and walk an entire DocC archive, using the DocC OpenAPI specs for the Archive JSON files.

Franklin: I'm going to reach out to ESG to confirm the naming change for the workgroup, and will touch base with a few folks who haven't been around for a while to see if they're well and still interested in participating with the workgroup.

Action Items

1 Like