![](https://files.koenig.kodeco.com/uploads/2023/07/docc_swift_automating_with_github_featured_banner@1.5x.png)
DocC Tutorial for Swift: Automating Publishing With GitHub Actions
Learn how to automate export a Docc archive file using GitHub Actions, and publish it on the internet using GitHub Pages as a static website host. By Natan Rolnik.
Sign up/Sign in
With a free Kodeco account you can download source code, track your progress, bookmark, personalise your learner profile and more!
Create accountAlready a member of Kodeco? Sign in
Sign up/Sign in
With a free Kodeco account you can download source code, track your progress, bookmark, personalise your learner profile and more!
Create accountAlready a member of Kodeco? Sign in
Sign up/Sign in
With a free Kodeco account you can download source code, track your progress, bookmark, personalise your learner profile and more!
Create accountAlready a member of Kodeco? Sign in
Contents
DocC Tutorial for Swift: Automating Publishing With GitHub Actions
25 mins
- Getting Started
- Understanding CI/CD and GitHub Actions
- What Is CI/CD?
- Meet GitHub Actions
- The Workflow YAML File
- Building the Documentation Locally
- Creating the Script
- Running the Script Locally
- Converting the Documentation to HTML
- Redirecting to the Documentation Page
- Setting Up GitHub Pages
- Activating GitHub Pages in Your Repository
- The GitHub Pages URL Format
- Configuring GitHub Actions
- Defining the Workflow File
- Publishing to GitHub Pages via Actions
- Running the Workflow on GitHub Actions
- Where to Go From Here?
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:
-
xcrun
is a tool that allows interaction with Xcode via command line, andxcodebuild
is the part of it responsible for building Xcode projects.docbuild
is the subcommand that builds the documentation for a given target. - Choose the scheme you want to build documentation for. In this case, it’s the
GivenWithLove
app. - 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 withgeneric/
. And because you don’t want to deal with code signing, chooseiOS Simulator
instead of an actual device. - 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
python3 -m http.server -d .docs
. If your macOS doesn’t have Python, you can install it with homebrew — brew install python3
— first. Once you have the local server running, the documentation will be visible at http://localhost:8000/documentation/givenwithlove/
.