Notes from the meeting today:
Documentation Workgroup Meeting - 28 July 2025
hackmd notes: Documentation Workgroup Meeting - 28 July 2025 - HackMD
Attendees:
- David Ronnqvist
- Joe Heck
- Dave Verwer
- Sofia Rodriguez Morales
- Franklin Schrans
- Vera Mitchell
- Rauhul Varma
Discussion:
cross-module linking / combined docs:
Joe - wanted to highlight the SwiftPM docs, now up on swift.org (although not linked from the top-level pages)
Joe - I'm exploring using the combined documentation linking now to present this content alongside PackageDescription & PackagePlugin API references, to be hosted on swift.org
Joe - while I was working through all this, there was a recent thread on the forums that ran into some issues with linking extensions within a combined set of docs:
FYI docc plugin issue
Joe - odd errors with moving files and permissions (using --checkout-path options to provide link to hosting causes DocC convert to fail · Issue #1248 · swiftlang/swift-docc · GitHub)
David - there was an earlier issue that we fixed earlier - had to do with how the build executable was installed that the user didn't have permission to access. Symptoms look similar, may be related - but thought this was sorted.
code-block presentation
Joe - continuing to move forward with doing somethig to expand code block presentations, moving to prototyping shortly
Joe - the two options I've found so far are directives vs. parsing language field area (akin to RustDocs). In Slack, ethan mentioned a possible preference to lean into parsing ratehr than directives, and I wanted to double check if directives were a "please don't go there" kind of thing for this.
David - syntactically you might not gain much - directives are stricter, default values - exact ordering, etc. Both code blocks and directives are block elements, so that's well aligned.
Franklin - I think Ethan was highlighting that we have directives for options and globalOptions for broader presentation controls that provide "for all of the package", not just the block in question.
"bare" docc in swift package
Joe - I've assembled an example that is akin to an article-only DocC catalog, but supports snippets. Was going to expand this further, to provide an integration test example, but second guessed myself and stopped on that effort for now.
David - it's an article-only example in disguise - it's actually a target of the package, but there's just no code to go along with it. So the module name is derived from the Package, not TechnologyRoot() directive in one of the pages.
Joe - Yes, and if you include TechnologyRoot inside, it can make a mess - duplicate modules, etc - that get a bit hard to wrangle. This is the pattern that'd being used for both Swiftly and SwiftPM documentation at the moment.
Snippets
Rauhul - has there been any discussion of multi-language snippets? For example C code that gets compiled and verified?
Rauhul - Talking with Doug Gregor and nailing down how to use APINotes with C interop with Swift, and want to ideally use that content as the documentation for itself. I might be wanting to reference explcit code in the docs itself.
Rauhul - I'd like to mix together APINotes and C code and use that as sourcing the for documentation
Adopting docc features into SPI
Franklin - want to look at adopting combined documentation as a feature for Swift Package Index. Is there anything we need to arrange from DocC's side to make it workable for SPI.
Dave - nothing stopping us from adopting other than the additions we added earlier
Dave - package switcher and version switcher. We can, and should, split those up.
Dave - have heard from a few folks attempting to use it that it didn't work as expected. We'd like to leverage it - and would reduce our merging of targets manually that we're doing today.
Franklin - another common request is linking across modules down the road - that's not something that works yet, currently limited to combined in a archive.
David - one of the hurdles is that links can change between versions. Blindly applying URLs to latest version can create links that don't resolve fully.
David - one of the solutions I've been exploring is letting authors specify where the content is hosted to enable linking into it.
Vera - worth nothing that package defines a base URL where the docs are hosted (akin to Rust) - links to documentation are prefixed with that URL in Rust.
Franklin - one of the advantages is that systems like SPI could provide a large index to reference into.
David - and the developer could override that from the CLI while building as well.
Sofia - how do we handle versions?
David - we know the version number, but the version doesn't make it's way into the URL. To support versions, it would need to have a convention to construct it. It's possible SPI could override the base path and then reference the version using their current mechanism.
Franklin - if SPI can look up package.resolved, determine the version from that, then we might have all the information we need.
David - we need a mode to allow to "trust" an external link will exist, but that doesn't currently exist. Currently we embed all the relevant links in symbols as nodes in the archive. All links today are relative, and we need to add some code to support absolute links to foreign packages.
Action Items
- Dave: talk w/ Sven about what options we'd can enable and how to get there.