1

When I build documentation in Xcode with Ctrl-Cmd-Shift-D, it includes my .docc catalog. When I run xcodebuild docbuild from the command line, it doesn't.

Why is this? Is it possible to tell xcodebuild to use a specific .docc catalog rather than just the doc comments?

I'm trying to automate the documentation build process for a Swift package, but I can't if it requires pressing a button in Xcode. Because it's a package, I have no project file or workspace to point to or modify.

Bbrk24
  • 739
  • 6
  • 22

1 Answers1

0

Yes, it is possible to build documentation from the command line with a documentation catalog.

For Swift packages, the way that the documentation catalog is associated with the target is by placing the documentation catalog in the same folder as the target’s source files, as mentioned in the “Documenting apps, frameworks, and packages” documentation.

Note that to use a documentation catalog in a Swift package—regardless if it’s in Xcode or in xcodebuild—the Package manifest’s Swift tools version needs to be 5.5 or later.

There shouldn't be any differences between “Build Documentation” menu item in Xcode and the xcodebuild docbuild action. You can confirm that the documentation catalog is or isn't passed to DocC by inspecting the build logs for both cases to see what arguments are passed to the docc executable.

David Rönnqvist
  • 56,267
  • 18
  • 167
  • 205
  • The package in this case is backwards-compatible with Swift 5.4, so requiring 5.5 would (in theory) be a breaking change. Is it possible to have the swift-tools-version comment indicate "use 5.5 if it's available, but 5.4 is fine"? – Bbrk24 Aug 17 '22 at 20:16
  • 1
    It's possible to have version specific package manifest files. That's for example how [Swift-Markdown](https://github.com/apple/swift-markdown/) uses a documentation catalog while remaining compatible with Swift 5.3. – David Rönnqvist Aug 31 '22 at 17:54