Description

Originally logged in swift-docc-plugin as swiftlang/swift-docc-plugin#99

I found that adding snippet connect (Snippets/somefile.swift) to a caused the preview-documentation command to intermittently fail in terms of rendering all the content. The top-level module symbol graph file (in my case, voxels.json) is missing in some iterations of invoking this command, and present in others.

After iterating with various plugin versions and nailing down that this was, in fact, an intermittent issue, I found the plugin to be invoking the following command:

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc preview /Users/heckj/src/Voxels/Sources/Voxels/Documentation.docc --emit-lmdb-index --fallback-display-name Voxels --fallback-bundle-identifier Voxels --additional-symbol-graph-dir /Users/heckj/src/Voxels/.build/plugins/Swift-DocC\ Preview/outputs/.build/symbol-graphs/unified-symbol-graphs/Voxels-7 --output-path /Users/heckj/src/Voxels/.build/plugins/Swift-DocC\ Preview/outputs/Voxels.doccarchive

I'm Opening this bug on swift-docc to continue to debug, and closing the issue on swift-docc-plugin since it doesn't appear to be related to the plugin content.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

When invoking swift package --disable-sandbox preview-documentation --target MyTarget on a package using swift-docc-plugin and containing any snippet content, I expect the documentation archive to be fully rendered. In my example. showing something akin to:

========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/voxels
========================================

Actual behavior

Intermittently, and accerbated by having snippet content in the project, the preview fails to render, showing instead:

========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/
========================================

And inside the docs-archive output path that preview used, the top-level target symbol graph JSON file (in my case, voxels.json) is missing. But this is intermittent, and repeated invocations will get different results.

Steps To Reproduce

• Get example Swift package (public repository)

git clone https://github.com/heckj/voxels
cd voxels

• Check out content before snippets were added:

git checkout 0.2.4

(commit shows 7048693)

• repeatedly invoke the preview command:

swift package --disable-sandbox preview-documentation --target Voxels

For 5 runs:

• content rendered

• content rendered

• content rendered

• content rendered

• content rendered

• Check out content with snippet content added:

git checkout 6089364

• repeatedly invoke the preview command:

swift package --disable-sandbox preview-documentation --target Voxels

For 5 runs:

• content missing
• content rendered
• content rendered
• content rendered
• content missing

Swift-DocC Version Information

'6.0.2' (included with Xcode 16.1)

Swift Compiler Version Information

swift-driver version: 1.115 Apple Swift version 6.0.2 (swiftlang-6.0.2.1.2 clang-1600.0.26.4)
Target: arm64-apple-macosx15.0