DocC Tutorial for Swift: Automating Publishing With GitHub Actions

The Workflow YAML File

GitHub Actions allows multiple workflows per repository, and each workflow describes its jobs and their steps using a YAML file. If you aren’t familiar with the syntax, YAML is a data serialization language widely adopted in the industry, mostly for describing configuration files. Here’s a short example of how it works:

# Key-value pairs are separated by a colon and a space
name: Jane Appleseed
age: 30
city: Cupertino

# Maps/Dictionaries use indentation to show nested key-value pairs
address:
  street: 19400 Homestead Road
  city: Cupertino
  state: CA
  zip: 95014

# Arrays are denoted by a hyphen and a space, and can contain any type of data, including nested dictionaries or arrays
fruits:
  - apple
  - orange
  - banana

As some people find the syntax confusing, you can visit Learn YAML in Y minutes if you want to learn more or have further doubts. Online linter tools, such as YAML Lint, are also valuable when validating a YAML file.

One must place all workflow files in the .github/workflows directory of a repository. A later section will instruct you on how to configure a workflow file for this tutorial’s purpose, but here are some of the most important and frequent properties:

• name: The name GitHub displays for actions that ran a workflow under the “Actions” tab. It’s optional, defaulting to the workflow file name.
• on: A list of events that trigger a workflow, such as pushes, new pull requests, webhooks and many more. You can see the full list of events in this link.
• jobs: A workflow consists of one or more jobs. Although they run in parallel, a job can have a dependency on another job, meaning it waits for another’s completion before starting.
• runs-on: Every job in a workflow can run in a different runner. The job must declare which operating system and machine to run on. Some of the options are macos-latest, macos-13, ubuntu-latest, ubuntu-18.04 and any other runner image present in this list.

The full list of options and parameters is available in the Workflow syntax for GitHub Actions page.

Building the Documentation Locally

Before moving straight to GitHub Actions, you should verify that you can build the documentation locally. To achieve that — and to prepare the next steps of the automation — you’ll create a bash script to consolidate the commands.

Creating the Script

First, open Terminal in the root directory of the sample project to create the script file. Enter the following command:

touch build-docc.sh

This creates a file named build-docc.sh. Before editing it, make the script executable by adding the appropriate permission to the file so you can run it later:

chmod +x build-docc.sh

Now, open it with your text editor of choice, and add the following command:

##!/bin/sh

xcrun xcodebuild docbuild \
    -scheme GivenWithLove \
    -destination 'generic/platform=iOS Simulator' \
    -derivedDataPath "$PWD/.derivedData"

Although it’s spread across four lines, this is a single command. Here’s what it does:

1. xcrun is a tool that allows interaction with Xcode via command line, and xcodebuild is the part of it responsible for building Xcode projects. docbuild is the subcommand that builds the documentation for a given target.
2. Choose the scheme you want to build documentation for. In this case, it’s the GivenWithLove app.
3. Both the app and package were built for iOS and import SwiftUI, so set the destination to iOS. Some xcodebuild actions don’t require a specific device or simulator to run on, so prefix the destination with generic/. And because you don’t want to deal with code signing, choose iOS Simulator instead of an actual device.
4. By default, xcodebuild generates its products and places them in the default derived data folder. Because you’ll need to find the documentation it generates, use a custom derived data location, with a known path, for easy access.

Running the Script Locally

Now, it’s time to use the script and generate the documentation locally. Back in Terminal, run the following command:

./build-docc.sh

After a few moments, the command should succeed. Once the xcodebuild output ends its explosion of characters, you’re ready to explore the generated documentation.

To find the DocC archives, open the .derivedData folder. Because it’s a hidden folder, you might not see it right away in Finder. To display hidden files and directories, press Command-Shift-.. Once you find it, open it and go to the Build folder, followed by the Products and the Debug-iphonesimulator directories. There, you’ll find the GivenWithLove.doccarchive file. If you can’t find the hidden folder or want to jump right into the final directory, run the following command:

open .derivedData/Build/Products/Debug-iphonesimulator

This is what you’ll see in that folder:

Double-click GivenWithLove.doccarchive, and Xcode will open the Developer Documentation window again. Notice how Xcode now displays it under the Imported Documentation section, as xcrun built it:

Congrats! You just generated your package’s documentation completely via Terminal commands — without interacting with the Xcode UI. In the upcoming sections, you’ll learn how to generate the same files on GitHub Actions, transform them into a website-compatible format and publish them to GitHub Pages.

Converting the Documentation to HTML

While it’s possible to view the DocC archive on a Mac, it’s still not the ideal format for publishing on the web. For that, Apple has added a command to docc that converts a .doccarchive input into a directory. This directory will contain all the necessary files for publishing the documentation as a static website.

Open the build-docc.sh file, and add the following lines after the existing command:

xcrun docc process-archive transform-for-static-hosting \
    "$PWD/.derivedData/Build/Products/Debug-iphonesimulator/GivenWithLove.doccarchive" \
    --output-path ".docs" \
    --hosting-base-path "" # add your repo name later

By running this command, you’ll tell docc where to find the input archive and where it should place the output files: in a folder named .docs. After creating your repository on GitHub, you’ll need to set the hosting-base-path argument, but you can leave it empty for now. Run the script again to check the result:

./build-docc.sh

After this command finishes, navigate to the .docs folder to see its contents:

open .docs