The background for this is my attempt at fixing an issue with DocC previews not reliably showing previews. I submitted a PR that was merged and consequently reverted when a number of tests in the swift-docc repo started failing in the overall CI build. My bad, for not checking that earlier. swift-docc
depends on swift-docc-symbolkit
, but the CI for the symbolkit library doesn't run all of DocC's tests, so it only showed up after merge.
I spent some of the weekend in the debugger, sorted out what was happening - or trying to - and that's led me to some broader questions that I wanted to pose and ask about.
The tests that are failing are all based around a single fixture (Snippets) which is set up as a bare docc catalog and a pre-generated symbolgraph file in JSON format.
The change I proposed reinforces what I thought was a valid assumption - that a snippet symbolgraph was always going to be an extension onto another symbolgraph. For current practical uses, that seems legit - but given the test setup, I'm not sure if that's correct. I think the only supported way to generate and use snippets today is within the construct of a Swift Package (a library, executable, etc - but most importantly there's an existing package structure, with a top-level module structure). So the relevant question that'll guide how to solve this is:
Was it intended that we could support a use-case scenario of a bare docc catalog with snippets to support just that catalog without having a wrapping Package structure or an associated library or executable that we're documenting?
I think the answer here is "No" or maybe "it would have been nice", but that functionally there isn't an easy way to enable this use case today. I'd love to hear from @bitjammer, @QuietMisdreavus, or @ronnqvist for some back history when this was being developed, if you recall and have the time.
If the answer is "yes, we want to support that", is there work outstanding that we can nail down for how to assemble a bare catalog and snippets - does it need a Swift Package manifest to structure the whole thing, was there another path to assembling this that was discussed but never firmed up, or is this in the realm of "It'd be awesome, but we haven't thought through the specifics" here?
The change I was proposing in the symbolkit loading logic was reinforcing the "snippets are always extending another symbolgraph", but if that's not correct, a different solution is required.
If that is a valid assumption, and including snippets can take a constraint of extending another symbolgraph, then I think the solution to enable the tests in swift-docc is to add another symbolgraph into that fixture that represents the "main" symbolgraph that is being extended.
I'd love a bit of nudging guidance in the direction the DocC team would prefer here.