DocC renderer crashing with no error message

[0xTim]

Description

When attempting to render the API docs for Vapor, the DocC renderer is crashing with no error message. This is all I get:

[1]    52475 trace trap   convert Sources/Vapor/Docs.docc --fallback-display-name "Vapor"    1.0.0 

This happens with both convert and preview

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

Documentation is generated correctly or an error showing why it can't generate the docs

Actual behavior

Renderer crashes with no error message

Steps To Reproduce

mkdir tmp && cd tmp
git clone git@github.com:vapor/vapor.git
cd vapor
mkdir -p .build/symbol-graphs
mkdir -p public/vapor
swift build --target Vapor -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert Sources/Vapor/Docs.docc --fallback-display-name "Vapor" --fallback-bundle-identifier codes.vapor.vapor.vapor --fallback-bundle-version 1.0.0 --additional-symbol-graph-dir .build/symbol-graphs --transform-for-static-hosting --output-path "public/vapor" --hosting-base-path "/vapor"    

Swift-DocC Version Information

5.7.2

Swift Compiler Version Information

swift-driver version: 1.62.15 Apple Swift version 5.7.2 (swiftlang-5.7.2.135.5 clang-1400.0.29.51)
Target: arm64-apple-macosx13.0

[0xTim]

This is a related issue to #351 - at least using Swift 5.6 doesn't display the issue and the docs are generated correctly. However I don't think it's the same as we build individual targets separately

[heckj]

Hey Tim,

I put this in slack, but thought it relevant to include here. The end-result of the diagnostics that led to my issue in #351 wasn't that I was building multiple targets, but that the symbol graphs that were included into the final docc convert included targets other than the specific one being generated. That's at least what caused the analyze - and I suspect may be causing this as well, at least if it's the same precondition that's triggering.

Were you able to get a backtrace that showed the detail of the precondition failure in this case?

[d-ronnqvist]

This is a related issue to #351 - at least using Swift 5.6 doesn't display the issue and the docs are generated correctly. However I don't think it's the same as we build individual targets separately

To me this looks like the same issue.

When I run

swift build --target Vapor -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs

I get 73 symbol graphs for 36 different targets in the same folder.

Even though only one target is specified (with --target Vapor) all of its dependencies (and their dependencies) still need to be built and all those are also emitting their symbol graph files into .build/symbol-graphs.

Building documentation with symbol graph files for multiple modules to DocC isn't an officially supported configuration. Even if the build succeeded the resulting DocC Archive would contain the documentation for all 36 targets, adding ~32000 pages to the output from various dependencies.

[d-ronnqvist]

If you're looking to build documentation for a single target I would refer you to the Swift-DocC plugin.

You can see an example of it being used in bin/update-gh-pages-documentation-site:

If you can't use Swift 5.6 or otherwise can't use the Swift-DocC plugin you can filter out the dependencies symbol graphs files before the documentation build. We do that in one of our documentation preview script.

If you're looking to build documentation for multiple targets, that's not something that Swift-DocC supports yet but it is something that we are working towards. See this Forums post.

[0xTim]

@d-ronnqvist the plugin is a last resort for us - we have around 60 packages and 100 or so targets to build documentation for and I don't want to be adding it as a dependency if we can avoid it.

I managed to work around this by only copying the symbol files so we're good on that front. I'll leave the issue open as it shouldn't be crashing with no error message.

I'll open a separate issue for multiple targets

[d-ronnqvist]

I'll open a separate issue for multiple targets

We already have #255 for this.

[0xTim]

@d-ronnqvist my particular error was DocC was overwriting other modules when running multiple converts but we can work around it

[0xTim]

Is it worth creating a separate issue for all of the fatalErrors() in the code with no error messages? Or would you prefer I just tack it on to this issue?

[d-ronnqvist]

@d-ronnqvist my particular error was DocC was overwriting other modules when running multiple converts but we can work around it

Do you know which assertion this hit? I tried so search for fatalError() but none of the results that I found looks related to what you describe.

[0xTim]

Sorry this got buried in an avalanche of GH notifications! I can't remember which fatal error I hit so I'll close this for now as we've worked around it