inconsistent recognition of the target provided to `preview-documentation`

[Joseph Heck]

Using docc-plugin 1.1.0, I'm seeing inconsistent results while running a preview command:

$(xcrun --find swift) package --disable-sandbox preview-documentation --target SwiftVizScale

In the best case, it does the right thing and the output that I get looks like:

Building for debugging...
Build complete! (0.15s)
Building for debugging...
Build complete! (0.12s)
Input: /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc
Template: /Applications/Xcode-14.3_beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
/Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc/Snippets.md:5:1: warning: Topic reference 'Scale/Snippets/ExampleSnippet' couldn't be resolved. No local documentation matches this reference.
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/swiftvizscale
========================================
Monitoring /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc for changes...

But sometimes, the preview URL that's presented doesn't include the link to the target:

Building for debugging...
Build complete! (0.15s)
Building for debugging...
Build complete! (0.12s)
Input: /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc
Template: /Applications/Xcode-14.3_beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
/Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc/Snippets.md:5:1: warning: Topic reference 'Scale/Snippets/ExampleSnippet' couldn't be resolved. No local documentation matches this reference.
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/
========================================
Monitoring /Users/heckj/src/Scale/Sources/SwiftVizScale/Documentation.docc for changes...

I'm a little unclear on why it's showing up in some, but not others - but it's a bit of a challenge to remember the URL extension without it being provided. And when it doesn't show the link, the content doesn't appear to be available at the url http://localhost:8080/documentation/swiftvizscale.

In the cases where I get the shorter URL, the preview basically "just doesn't work" and the only workaround is to re-run the command until it does.

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

swift package --disable-sandbox preview-documentation --target SwiftVizScale provides a URL that you can click on and shows you the contents.

Actual behavior

In some iterations of running this command, the url provided is Address: http://localhost:8080/ and no content is available even at the extended URL.

Steps to Reproduce

git clone https://github.com/swiftviz/Scale
cd Scale
swift package update
swift package --disable-sandbox preview-documentation --target SwiftVizScale

Repeat 3-5 times, killing the server and re-running the preview-documentationcommand. For me, it's resulting in the broken setup in a 1:2 to 1:3 ratio.

I have repeated this with the main branch as well as the 1.1.0 branch - same results.

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0 and branch: "main"
Swift Compiler version::

swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.117.11 clang-1403.0.22.8.60)
Target: arm64-apple-macosx13.0