Automating DocC Deployment with a Shell Script

Publishing project documentation is one of those things that should be easy – but often isn’t. Apple’s DocC makes it simple to generate great documentation for Swift and Xcode projects, but getting that documentation online as a static website requires a few more steps.

I wanted a process that’s fast, reliable, and easy to run locally or in a CI pipeline. So I put together a small shell script that does exactly that:

• Builds the DocC archive
• Transforms it for static hosting
• Deploys it to my web server using SCP

Here is the script which I am using for my projects (including TBRESTClientLib)

#!/bin/zsh
#
# Build, convert and deploy your DocC documentation to a webserver using SCP
# Suitable for local use or CI/CD pipelines
#
# Script by Johannes Kinzig | mail@johanneskinzig.com | https://johanneskinzig.com
#
# Usage:
#   ./build-deploy-docc.sh
#
# Requires: xcodebuild, xcrun (DocC), scp

# --- Config ---
BUILD_SCHEME_NAME=TBRESTClientLib
SCP_DESTINATION_URL=scp://$SCPUSER@kinzigdoccserver:22/kinzig-developer-docs_com/tbrestclientlib/
WWW_URL=https://tbrestclientlib.kinzig-developer-docs.com/documentation/tbrestclientlib

# --- Check prerequisites ---
if [ -z ${SCPUSER+x} ]; then
  echo "Error: SCPUSER is not set. Please run:"
  echo "  export SCPUSER=YourScpUsername"
  exit 1
fi

# --- Safety settings ---
set -euo pipefail

command -v xcodebuild >/dev/null 2>&1 || { echo "Error: xcodebuild not found."; exit 1; }
command -v xcrun >/dev/null 2>&1 || { echo "Error: xcrun not found."; exit 1; }
command -v scp >/dev/null 2>&1 || { echo "Error: scp not found."; exit 1; }

# --- Build paths ---
BUILD_DIR="./.doccbuilds"
ARCHIVE_DIR=$BUILD_DIR/build/Build/Products/Debug/$BUILD_SCHEME_NAME.doccarchive
PUBLISH_DIR=$BUILD_DIR/publish

# --- Functions ---
function cleanup {
  echo "Cleaning up..."
  rm -rf -- $BUILD_DIR
}
trap cleanup EXIT

# --- Build documentation archive ---
echo "🔨 Building DocC archive for scheme: $BUILD_SCHEME_NAME"
xcodebuild docbuild -scheme $BUILD_SCHEME_NAME -derivedDataPath $BUILD_DIR/build -destination platform=macOS

# --- Convert for static hosting ---
echo "📦 Transforming archive for static hosting..."
xcrun docc process-archive transform-for-static-hosting $ARCHIVE_DIR --output-path $PUBLISH_DIR

# --- Deploy via SCP ---
echo "🚀 Uploading to $SCP_DESTINATION_URL ..."
scp -rp $PUBLISH_DIR/* $SCP_DESTINATION_URL

# --- Done ---
echo "✅ Documentation now available at: $WWW_URL"
echo "(CMD+double-click on URL to open in your default browser)"

How It Works

1. Configuration

At the top, set your build scheme (BUILD_SCHEME_NAME), your server destination (SCP_DESTINATION_URL), and the public HTTP/S-URL where the docs will be hosted.

2. Checks & Safety

• Ensures SCPUSER is set before running
• Stops immediately on errors (set -euo pipefail)
• Verifies that required tools (xcodebuild, xcrun, scp) are available

3. Build

Runs xcodebuild docbuild to generate the .doccarchive for your scheme.

4. Transform

Uses xcrun docc process-archive transform-for-static-hosting to convert the archive into a static website (HTML, JS, CSS).

5. Deploy

Uploads the static files to your server using scp -rp.

6. Cleanup

Automatically removes the temporary build directory once the script finishes (or fails).

Usage

1. Make the script executable: chmod +x build-deploy-docc.sh
2. Set your SCP username: export SCPUSER=myusername
3. Run the script from your project root: ./build-deploy-docc.sh

Your documentation will be built, uploaded and published at the configured URL. Doing a CMD+Double-Click on the HTTP/S url displayed in the terminal opens your default webbrowser at this location. That’s it!

Why I Like This Approach

• A single command produces the desired result: build, convert, deploy – all in one step
• The generated output is plain HTML, ready to be served by a basic web server (no complex configuration required)
• A shell script works perfectly for local development in small teams, but can also scale to integrate with a CI/CD pipeline

📬 Stay in the loop?

If you’d like to stay up to date with future technical guides and project insights,  subscribe to my newsletter. I share practical knowledge, lessons learned, and updates – no spam, just content for developers and engineers.