The docc-plugin preview-documentation sometimes fails to preview content with snippets

[heckj]

The docc-plugin preview-documentation command appears to be failing to generate a module index page when snippets are added to the project.

This is with Swift 6.0.2 and swift-docc-plugin 1.4.3 (Xcode 16.1 release).

When I run the command to preview my documentation:

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

I see the (mostly) normal output:

Building for debugging...
[1/1] Write swift-version--58304C5D6DBC2206.txt
Build of product 'snippet-extract' complete! (0.18s)
Building for debugging...
[1/1] Write swift-version--58304C5D6DBC2206.txt
Build of target: 'Voxels' complete! (0.15s)
Input: /Users/heckj/src/Voxels/Sources/Voxels/Documentation.docc
Template: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/
========================================
Monitoring /Users/heckj/src/Voxels/Sources/Voxels/Documentation.docc for changes...

A difference from what I expected is that there's no documentation/voxels on the URL presented, which happens on other projects.
When I opened a browser, going to http://localhost:8080/documentation/voxels, the JS browser error reports a missing file voxels.json.
Looking at the .build directory, I see .build/plugins/Swift-DocC Preview/outputs/Voxels.doccarchive/data/documentation, the directory of which voxels within it and a collection of all the symbols in JSON format. However, there isn't a voxels.json file in that directory.

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

Describe what you expected to happen.

Actual behavior

Describe or copy/paste the behavior you observe.

Steps to Reproduce

git clone https://github.com/heckj/voxels
cd voxels
git checkout 7c70985
swift package --disable-sandbox preview-documentation --target Voxels

(URL for the above shows http://localhost:8080/documentation/voxels and resolves correctly)

git checkout 6089364
swift package --disable-sandbox preview-documentation --target Voxels

(URL for the next commit shows http://localhost:8080/ and fails to resolve)

The only difference between these two commits is adding the file Snippets/example-snippet.swift to the project.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.4.2 for example, or a commit hash.
Swift Compiler version: Output from swiftc --version:

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

[heckj]

I just thought to try swift-markdown, but it doesn't exhibit the same behavior. When running swift package --disable-sandbox preview-documentation --target Markdown on that project, the address shown is http://localhost:8080/documentation/markdown and the documentation renders as expected. That said, I'm not sure what the meaningful difference is between the two projects in terms of how it generates the results.

[heckj]

I reproduced the issue with the main branch of docc-plugin as well. And iterated through a few commits. The issue appears to be happening when there's a snippet added, but no curation or reference to the symbols added into the catalog.

Once some curation and reference is added, that extends to the primary documentation page for the catalog, the content renders correctly. If there is no @Snippet(path:"") reference in the content, the whole content doesn't render correctly.

[heckj]

I switched back and forth between 1.4.3 and main, with the same results in both cases, so the underlying issue may be in DocC, not in the plugin.

Working when there's a @Snippet reference:

git commit with snippet curated into catalog

git checkout c7dcaf514abc318c1ab7aded31b3a4b4ebb35023
swift package update
rm -rf .build # clean the build
swift package --disable-sandbox preview-documentation --target Voxels

-->

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

Prior commit with only the snippet

git checkout 6089364a89cfa1360c26a85d6ad005994274833e
rm -rf .build # clean the build
swift package --disable-sandbox preview-documentation --target Voxels

-->

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

5 iterations of this same command:

• no content
• content rendered
• no content
• content rendered
• no content

And a variation I didn't expect

I moved back forward to verify - the commit that previously worked - and used this same sequence of commands, and the contents didn't resolve

git checkout c7dcaf514abc318c1ab7aded31b3a4b4ebb35023
swift package update
rm -rf .build # clean the build
swift package --disable-sandbox preview-documentation --target Voxels

-->

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

Running the following steps repeatedly (5 iterations)

git checkout c7dcaf514abc318c1ab7aded31b3a4b4ebb35023
rm -rf .build # clean the build
swift package update
swift package --disable-sandbox preview-documentation --target Voxels

• no content
• no content
• content rendered
• content rendered
• content rendered

Since this seems to be more of a race-condition issue, I jumped back to a commit before I added snippets to see if that's a factor:

git checkout 0.2.4
rm -rf .build # clean the build
swift package --disable-sandbox preview-documentation --target Voxels

5 iterations:

• content rendered
• content rendered
• content rendered
• content rendered
• content rendered

From this, I'm hypothesizing that there's a race condition in there somewhere, acerbated by Snippets existing that doesn't otherwise normally show up.

[heckj]

Double checking with main branch of swift-docc-preview on commit with both snippet and content curated into the catalog:

rm -rf .build
swift package --disable-sandbox preview-documentation --target Voxels

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

Repeating just the preview command (without clearing the build):

• after a content missing build:
  • content missing
  • content rendered
  • content missing
  • content rendered
  • content rendered

Based on this, trying to alleviate things by clearing the .build portion of this doesn't appear to make a difference.

I snapshotted the .build directory after a working, and non-working, example and compared the two:

ls -l .build/plugins/Swift-DocC\ Preview/outputs/Voxels.doccarchive/data/documentation/
total 40
drwxr-xr-x  53 heckj  staff   1696 Nov  4 10:10 voxels
-rw-r--r--   1 heckj  staff  18831 Nov  4 10:10 voxels.json

ls -l .missing/plugins/Swift-DocC\ Preview/outputs/Voxels.doccarchive/data/documentation/
total 0
drwxr-xr-x  53 heckj  staff  1696 Nov  4 10:09 voxels

And indeed, voxels.json is missing from the non-functioning version, but this content appears to be regenerated on every iteration of the preview-documentation command.

[heckj]

I broke this down and started down the path of debugging the plugin, only to realize the issue is upstream in docc. The raw command being invoked:

/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

Is what appears to have the race condition.
In repeated tests of just this command:

• no content
• no content
• content rendered
• no content
• no content

So the issue appears to be in the underlying docc preview command.

[heckj]

detail migrated to swiftlang/swift-docc#1084 and closing this, since it's not docc-plugin specific.