DocC Snippets - snippet reference not resolved

Development Swift-DocC
1

With swift 5.7 formally out the door, I was back at experimenting with (and learning how to potentially use) the snippets feature.
With the latest Xcode (both release & beta (14.1 beta 3)), snippets are compiling without issue both in Xcode, and directly using swift on the command line.

But when I'm trying to reference a snippet from a sample article, I'm repeatedly getting the warning:

Topic reference '...' couldn't be resolved. No local documentation matches this reference.

I made a sample project to illustrate what I was seeing (GitHub - heckj/DoccSnippetExample) - and when I render the docs (using swift-docc-plugin, or by invoking Xcode 14.1 beta 3's "Product > Build Documentation"), I get that error.

swift build works great.
swift run ExampleSnippet3 does it's work and prints the result correctly, but a build fails.

Is there anything I need to be doing to enable snippets?

The doc build command that's simplest and showing the error is:

swift package generate-documentation --target DoccSnippetExample

with the output:

Generating documentation for 'DoccSnippetExample'...
Building for debugging...
Build complete! (0.16s)
Converting documentation...
/Users/heckj/src/DoccSnippetExample/Sources/DoccSnippetExample/Documentation.docc/AnArticle.md:13:1: warning: Topic reference 'DoccSnippetExample/Snippets/ExampleSnippet3' couldn't be resolved. No local documentation matches this reference.
Conversion complete! (0.07s)
Generated DocC archive at '/Users/heckj/src/DoccSnippetExample/.build/plugins/Swift-DocC/outputs/DoccSnippetExample.doccarchive'

The snippet reference in the article content is:

@Snippet(path: "DoccSnippetExample/Snippets/ExampleSnippet3")

I can open a bug with this detail if this is unexpected, but I suspect that I'm just missing something small. Any suggestions? Anyone got this working end to end with a sample I could even compare?

2

Hi Joe! Try the main branch of swift-docc-plugin. I don't think that tag has snippet support, or at least not all of it.

1 Like
3

Thanks Ashley!

That did the trick all right. Xcode still doesn't like building that documentation, so I'm presuming it's using a path other than through the swift-docc-plugin, and gives that error - but if I use the plugin and CLI to invoke the build or preview, it's correctly including snippets in articles.