SymbolGraphs and Snippets - requesting a bit of guidance/expectation about the current implementation

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. :frowning_face:

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. :bowing_man:

2 Likes

Related to this, I've taken the assumption that it's acceptable to expect a main symbolgraph with any existing test of a 'snippets' symbolgraph, for the purposes of trying to get the preview w/ snippets bug resolved. To that end, I've made a PR in the swift-docc repo that changes a test fixture to match this expectation, which in turn lets the PR that we'd merged earlier, and have to revert, flow through. That PR is now back up on swift-docc-symbolkit (Support snippet symbolgraph by heckj · Pull Request #95 · swiftlang/swift-docc-symbolkit · GitHub), but is dependent on race condition with `docc preview` that appears to be acerbated by including snippets in DocC content · Issue #1084 · swiftlang/swift-docc · GitHub.

All of this is predicated on the concept of a "main" symbolgraph in DocC's guts, and that snippets are always an extension of some other "main" symbolgraph. If that's not valid, and other requirements that aren't clear to me now are in play here, I'm happy to update the PRs and change how this fix is implemented in order to accommodate those requirements.

We talked about this in the latest Documentation Workgroup meeting and Joe and I also talked about this separately.

For visibility I thought that I'd repost the same information / brief summary of that conversation here.


I personally don't know—and if I ever knew I have since forgotten—if there was ever an intention to support documentation of snippets that doesn't also contain documentation about some library or executable that the snippets are about.

That said, I'm not sure if that documentation setup would be likely and it if would be particularly useful to developers. If the snippets are about a library or executable, why wouldn't they be part of the documentation for that library or executable?

When Joe and talked about this, Joe brought up The Swift Programming Language (TSPL) as a unique example where this could be relevant because it's not about a library. However, we agreed that in this case snippets could easily be supporter by adding a "main" symbol graph file without any symbols and using that module page as the root of the documentation.

As far as I know and can tell, it seems very sensible to formalize that that a snippet symbol graph is interpreted as an extension onto another symbol graph.

1 Like