The Documentation Workgroup will be holding its next meeting on Monday, February 24th, 2025 from 8:00am to 9:00am PT (or see the time in your own timezone).
This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.
Meeting notes for this meeting will posted in this thread shortly after.
Please propose agenda items in this thread.
hackmd notes: Documentation Workgroup Meeting - 24 Feb 2024 - HackMD
(Joe) I have a PR pending (adds a base symbolgraph for Snippets test fixture by heckj · Pull Request #1160 · swiftlang/swift-docc · GitHub) for swift-docc that it replacing a text fixutre for snippets and wanted to make sure there wasn't an earlier expectation/requirement that I'm stomping on. Current fixture is a bare catalog and a snippet-only extension, which I think isn't an actual use case today, as anything with snippets would generally have a SwiftPM package (and code) that provides a 'main' symbolgraph. David and I talked briefly about this in another meeting, but I wanted to verify here.
(David) I couldn't remember any specific requirements along these lines, if I did know - I've forgotten, but I tend to lean on "is there a place this should have happened". Only use case I've seen is the one Joe called out which would be something like TSPL and using snippets within it.
(Joe) The workaround in a scenario like that - where you wanted to use snippets with a "bare" catalog of concent - would be to generate a blank or empty symbolgraph as the main for the project.
(Franklin) Sounds like the only place where this might be desired is in writing about Swift itself. I don't recall any requirements about this either.
(Kyle) question in SPI in forums
Any existing tools that can help us merge two different symbolgraphs. I work in libraries for two platforms, #ifdef a few pieces to each platform, but more cross-platform. Want the docs to reflect iOS and macOS with availability notations in the same docs.
Does anyone know Is there any tool which can help merge 2 symbol graph? (eg. The same package generate one for iOS and the other on macOS)
The discord message link on SPI Discord
(Vera) not a standalone tool, but DocC will do this. For the use case where there's SPI, you need to build both separate platforms and then provide both into DocC.
(David) Place this seems like it should belong is SPM or the docc-plugin. There's not currently support for docc plugin to build cross platform. Simulating multiplatform build would likely be very fragile.
(Sven) Would be a huge can of worms, since the builds happen independently. We aren't dealing with symbolgraphs at all, so we'd need to pull that apart and mix. Would be far better if that could happen "upstream" in Docc, we'd far prefer that. Workarounds would mean focusing on build and extraction of symbolgraph that we'd need to then later re-assemble.
(Vera) The ultimate source of support is SwiftPM itself. There may be a hack around this, where you can build documentation during build. It might be possible to run both, find the derived data directory, and extract the symbolgraphs.
(Sven) Bigger problem is running build twice, which hits up against 10min timeout we have, and it's not clear when we'd need to do that.
(Vera) I don't think there's a good way to do that right now.
(Franklin) Maybe something we can leverage from the updating of swift-build project within SwiftPM.
(Sven) Any way we can get a feel for how many packages fall into this categorization? (that want dual-platform representation in the final docs?)
(Franklin) This sounds like a longer term thing.