DocC Tutorial for Swift: Automating Publishing With GitHub Actions

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

Redirecting to the Documentation Page

If you were able to serve the docs locally, you might be wondering why the root page displays an error. This is because DocC organizes the files for static hosting in the following structure:

As you can see, the givenwithlove directory is located under documentation. To view the documentation of an app or package, the address should be in the pattern host.com/documentation/your-product-name instead of accessing the root page (host.com). Accessing the root page results in an error.

To help your readers, you can replace the .docs/index.html file with a redirect, and the browser will lead them directly to the correct path.

Open the build-docc.sh file again, and in a new line, add the following:

echo '<script>window.location.href += "/documentation/givenwithlove"</script>' > .docs/index.html

This will redirect the root page to the documentation. Rerun build-docc.sh, restart your local server, and when you visit http://localhost:8000/, you’ll be redirected to the documentation page.

Now, it’s time to move on and get your hands on GitHub!

Setting Up GitHub Pages

So far, you’ve learned how to generate the .doccarchive file and convert it into a format suitable for static hosting. The next step is defining the workflow file for running the same script you ran locally and publishing the content to GitHub Pages.

GitHub Pages is another service — you guessed right, from GitHub — that allows developers to host static website content for a personal profile or specific projects. It even allows custom domains with HTTPS support!

Activating GitHub Pages in Your Repository

Create an empty repository on GitHub for this tutorial. GitHub Pages only works with private repos if you’re on the Pro plan. Otherwise, if you have a free GitHub account, make sure you create a public repository. To make pushing your commits smoother, don’t include a Readme or a .gitignore file.

In your browser, open your new repository, and go to the Settings tab. In the left pane, under the Code and automation section, click Pages. In the Build and deployment section, click the Source menu, and choose GitHub Actions. There are two ways of deploying to GitHub Pages, and although still in beta, publishing to Pages via Actions is the way GitHub recommends (instead of pushing to a specific branch).