Documentation Workgroup Meeting - 19 May 2025
hackmd notes: Documentation Workgroup Meeting - 19 May 2025 - HackMD
Attendees:
- Joe Heck
- Sven Schmidt
- David Ronnqvist
- Kyle Ye
Discussion:
Doc Testing
From Sven:
As you may have seen, we had a problem generating correctly rendering docs in SPI when we updated to 6.1 and I'd like to brainstorm what we can do to detect that a) at all, automatically and b) detect it earlier than when we update to a new compiler version.
The problem with us detecting it is that we're at the end of a long chain and workarounds tend to be complex (like using the 6.2 renderer now) and until we detect the issue, we persist faulty output that is hard to fix up after the fact.
Sven: Follow on to recent issues with Swift 6.1 and documentation building system. Tests in place to verify that builds are passing and that docs exist - but only to the point that HTML exists. David helped diagnose the last problem (thank you).
- I want to have some way to verify that content is more effectively working, esp. hosting over 1000 repositories. We were lucky that PointFree noticed the docs were faulty and were able to work around this.
David Ronnqvist: Doc sidebar not showing correct module in Swift 6.1 generated docs · Issue #3786 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub
Sven: Would be great to understand if there's something to interrogate to know if everything exists as planned.
-
JavaScript investigation would work, as there was content - just some pieces were unexpected there.
-
What we can do, if there's an issue, is slow down the rollout for doc generation.
-
Is there any exemplar that we could use to generate on quickly - a well-known sample scenario that can be testing and interrogated?
David: This was a renderer bug that was specific to multiple target docc generation. Or the index was manually generated.
- Docc didn't change it's output, but the renderer changed its interpretation of it. Stuff rendered on the page.
Sven: Some of the repos are hard to know - SwiftNIO for example, doesn't have a sidebar.
- Is there a healthcheck probe that we can mechanically trigger?
David: There might have been a console warning or something about navigator issues, but unfamiliar with that code to know if that would show up.
Sven: I do believe the Nightwatch tool we briefly looked into showed console errors. Runs a chrome browser and inspects elements on the page. Slow, but might be an avenue to explore.
Joe: We'd also need a well-known, agreed upon (unchanging) source to provide a regression testing scenario.
Sven: I'd be happy to help provide, but don't know enough about the javascript side of the equation to know what and how to test it.
- Feeling very nervous about verifying that this is all correctly load bearing.
Sven: finestructure / spi-doctest · GitLab
<- nightwatch test system prototype.
Joe: offer to help assemble some parts to make this work. Need to get some permissions to support this and inquire with the folks working on Renderer to see if they have any advice.
Action Items
- Joe: Follow up internal to Apple to inquire as to advice here.
- Sven: open discussion on the forum to discuss and drive further.