CODEWITHSUNDEEP
xcodecontinuous-integrationxcodebuilddocc
colin
colin

Reputation: 1008

How to build DocC documentation from CLI

So I have been browsing the web for a while now and can't seem to find an answer on how to build the native DocC Xcode documentation using a CLI command.

Both the xcodebuild commands and Fastlane do not provide a command to build the documentation - as far as I know.

The docs are supposed to be built inside a CI/CD Github Actions workflow. If there are other methods to accomplish this, any help is appreciated.

Upvotes: 7

Views: 3966

Answers (4)

marc-medley
marc-medley

Reputation: 9832

GitHub apple/swift-docc Getting Started with DocC provides Command Line Interface (CLI) information for Swift-DocC standalone documentation.

### For Linux/macOS Swift Toolchain based installations:
docc --help

### For Xcode based installations:
xcrun docc --help

# OVERVIEW: Documentation Compiler: compile, analyze, and preview documentation.
# 
# USAGE: docc <subcommand>
# 
# OPTIONS:
#   -h, --help              Show help information.
# 
# SUBCOMMANDS:
#   convert                 Converts documentation from a source bundle.
#   index                   Create an index for the documentation from compiled data.
#   preview                 Previews documentation from a source bundle.
#   process-archive         Perform operations on DocC Archives.
# 
#   See 'docc help <subcommand>' for detailed help.

Upvotes: 0

XLE_22
XLE_22

Reputation: 5671

To complement the initial answer, I'd like to mention this complete summary of all the WWDC21 videos regarding DocC that contains precious information about automation. 🤓

Indeed, there's a feature in Xcode 13 for building documentation through the command line that includes the docbuild action with many possible options as described below. 🤩 enter image description here Besides, Xcode 14 fosters the DocC archive content deployment at the root of a web server thanks to its new compatibility with most web servers. 🤩
enter image description here

Even if a solution has already been provided by @Colin 👍, I deemed it important to append some information that may be crucial for some. 😉

Upvotes: 3

Pranav Kasetti
Pranav Kasetti

Reputation: 9925

Host and Automate your DocC documentation ☁️

Tl;dr

I tweaked the xcodebuild docbuild for modular projects as below:

xcodebuild -project ModularSlothCreator.xcodeproj -derivedDataPath docsData -scheme ModularSlothCreator -destination 'platform=iOS Simulator,name=iPhone 13 Pro Max' -parallelizeTargets docbuild

I also tweaked the docc site generation using the transform-for-static-hosting flag:

$(xcrun --find docc) process-archive transform-for-static-hosting "$ARCHIVE" --hosting-base-path ModularSlothCreator/$ARCHIVE_NAME --output-path docs/$ARCHIVE_NAME

BONUS: Automate DocC with GitHub Pages and CI 🍀

I've updated the original demo showcased at WWDC with support for static hosting of modular App targets (rather than only supporting a single Swift Package announced at WWDC) using GitHub Pages without needing to define a server configuration for convenience in my blog post.

Upvotes: 4

colin
colin

Reputation: 1008

Apple has added a new command to xcodebuild tools:

xcodebuild docbuild

You can also take a look at the WWDC presentation "Host and automate your DocC documentation". Start watching from 7:06 min onwards for DocC automation: https://developer.apple.com/videos/play/wwdc2021/10236/

Upvotes: 6

Related Questions