Failure to build swift-book using Xcode docc

[ahmedhumza94]

Hello, I am failing to build the swift-book on my Mac (14.1) using docc as part of Xcode (15.3).

I run

xcrun docc preview TSPL.docc

The error I get is ambiguous

zsh: trace trap xcrun docc preview TSPL.docc

Anyone else run into this?

[amartini51]

Can you try building DocC from source? https://github.com/apple/swift-docc The Swift 5.10 version of DocC had some issues related to unresolved links, which caused a crash when building this book, but current 'main' works in release mode. (In debug mode, it fails an assertion and crashes.)

The Swift 5.9 version of DocC also works. That's what I used to publish the Swift 5.10 version of the book. So if you have an older Xcode installed, its DocC should work also.

[ahmedhumza94]

Thanks I built the Swift 5.9.2 tagged release of swift-docc and was able to successfully use that to build a preview of the book.

[d-ronnqvist]

The Swift 5.10 version of DocC had some issues related to unresolved links, which caused a crash when building this book

That is completely unrelated and doesn't cause any crashes. Version 5.10 uses a different formatter to display diagnostics on the command line. This diagnostic formatter reads lines of code from the source file to highlight the source range of the diagnostic. Unfortunately the initial implementation of this diagnostic formatter makes an assumption that the diagnostic ranges will always be valid and exist in the source file and crashes with out-of-bounds-issues if they're not.

On the 'main' branch this diagnostic formatter guards against diagnostic ranges that don't exist in the source file. Like Alex noted above, in debug builds we intentionally assert when trying to format a diagnostic range that doesn't exist in the source file so that we can fix the invalid diagnostic ranges at the source. The specific diagnostics that fail in the swift-book have offset source ranges in the markdown. I don't know if this is because DocC offsets them or if they're created with offset ranges from parsing the markup.

To workaround this crash you can pass the --ide-console-output flag to opt out of the new diagnostic formatter and use the diagnostic formatter that's more aimed towards being parsed by tools or scripts.

[7ombie]

A bit more information...

I tried building the Book for swift-6-beta-5 on an M1 Mac running Sonoma 14.5, and had the same issue. When I added the flag that @d-ronnqvist suggested (--ide-console-output), it built, and seems to be working, but I got a bunch of warnings as well:

❯ xcrun docc preview TSPL.docc --ide-console-output
Input: /Users/carl/Projects/SwiftBook/TSPL.docc
Template: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
/Users/carl/Projects/SwiftBook/TSPL.docc/LanguageGuide/TheBasics.md:256:42: warning: '`' doesn't exist at '/The-Swift-Programming-Language/TheBasics'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/LexicalStructure.md:102:7: warning: '`class`' doesn't exist at '/The-Swift-Programming-Language/LexicalStructure'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/LexicalStructure.md:104:3: warning: '`x`' doesn't exist at '/The-Swift-Programming-Language/LexicalStructure'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/LexicalStructure.md:142:88: warning: '`' doesn't exist at '/The-Swift-Programming-Language/LexicalStructure'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/LexicalStructure.md:142:145: warning: '`' doesn't exist at '/The-Swift-Programming-Language/LexicalStructure'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/LexicalStructure.md:417:37: warning: '`' doesn't exist at '/The-Swift-Programming-Language/LexicalStructure'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/SummaryOfTheGrammar.md:49:88: warning: '`' doesn't exist at '/The-Swift-Programming-Language/SummaryOfTheGrammar'
/Users/carl/Projects/SwiftBook/TSPL.docc/ReferenceManual/SummaryOfTheGrammar.md:49:145: warning: '`' doesn't exist at '/The-Swift-Programming-Language/SummaryOfTheGrammar'
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/the-swift-programming-language
========================================
Monitoring /Users/carl/Projects/SwiftBook/TSPL.docc for changes...

Hope this is useful.

[amartini51]

@7ombie That list of warnings is due to a known issue. You can read swiftlang/swift-markdown#93 and swiftlang/swift-markdown#93 for full details.

DocC adds a double backtick syntax for API links to markdown. For example, from within the standard library docs, you can write ``String`` to make a link to the String docs. This is generally much more convenient than the other ways to make a link.

However, doubling a backtick is also how you write code voice with backticks inside of it. For example, the first warning from Lexical Structure:

For example, `class` isn't a valid identifier,
but `` `class` `` is valid.

This produces the word "class" surrounded by backticks, all set in code font. But DocC also checks whether `class` is a valid link destination, and warns because it can't make a link to it.

[7ombie]

Ahh. Thank you, @amartini51. Good to know. Sorry for the noise.