DocC Tutorial for Swift: Automating Publishing With GitHub Actions

In the software development routine, it’s common to perform repetitive tasks manually. But this comes with a price: It’s both tedious and error-prone. Fortunately, the industry has developed solutions that address the need to automate the repetitive processes a developer or a team must perform.

In a previous tutorial, Mina H. Gerges walked through using DocC and Xcode to generate documentation for an app and a Swift package and then export them in the DocC archive format.

In this follow-up tutorial, you’ll learn how to automate exporting a DocC archive file using DocC on GitHub Actions and then publish it on the internet using GitHub Pages as a static website host.

Along the way, you’ll learn:

• How to generate the documentation in the DocC using Xcode and the command line.
• How to configure a GitHub repo to host the generated documentation.
• How to set up GitHub Actions to regenerate and republish the documentation when you push changes to the repo.

You’ll build documentation for a package that requires SwiftUI and the iOS SDK. For that reason, this tutorial uses DocC integration within Xcode, which requires a Mac host. If you’re willing to document a pure Swift package that can be built on Linux, you might use the Swift-DocC plugin directly, as explained in this page. Besides that difference, you can still follow along to understand how GitHub Actions works.

Getting Started

Start by clicking Download materials at the top or bottom of this tutorial. Open GivenWithLove.xcworkspace in the Starter directory in Xcode.

You’ll notice the workspace contains the app as well as a Swift package. For both, Xcode can build the documentation. While this tutorial is about calling DocC via command line, you can use the Xcode UI to build the documentation. To do so, select any simulator as a run destination rather than a device or Any iOS Device. Then, open the Product menu, and select Build Documentation.

After a few seconds, Xcode builds the documentation and then automatically opens it in the Developer Documentation window.

In this tutorial, you’ll learn how to execute this same Action from the command line, export it to HTML and host it using GitHub Pages — all powered by GitHub Actions. But before starting and getting your hands on the keyboard, here’s a quick review of what CI/CD and GitHub Actions mean.

Understanding CI/CD and GitHub Actions

If you work with mobile or web development, there’s a good chance you’re familiar with the terms continuous integration (CI), continuous delivery (CD) and GitHub Actions. If they’re new to you, no worries: You’re in the right place!

What Is CI/CD?

When adding new features or fixing bugs, you need to test your new code and verify you didn’t break anything else. Or you might work on an SDK and need to publish the updated documentation. But doing it manually — again and again — is far from ideal. To solve this issue, and to reduce human error, a good practice is automating these tasks.

Continuous integration is the automation of building and testing code whenever the version control system, such as Git, detects new changes. Usually, using webhooks, the Git remote repository updates the CI system about the changes. For example, when the main branch has a new commit, when someone creates a pull request or when a new tag is available, it updates the CI, which, in turn, runs specific workflows depending on the trigger.

Another term that frequently appears alongside CI is CD, which stands for “continuous delivery”. Besides compiling and running tests on the new code, developers often want to preview their changes without performing manual operations. A CD system (no, not those old sound systems from the ’90s) addresses this need by deploying a preview website or a beta app, or even fully releasing an app or a website.

In general, CI/CD runs on a remote, hosted computer, with the objective of offloading time and resources from a developer’s machine, in addition to the round-the-clock availability.

Meet GitHub Actions

Although Git and CI/CD aren’t interchangeable concepts, they’re essentially intertwined. By definition, CI/CD must have access to the source code and be alert for the events mentioned above. Because of the natural relationship between these tools, in 2018, GitHub launched its own workflow automation tool. By providing both Git and CI/CD, GitHub can centralize them in a single place, allowing for a faster, seamless developer experience.

A repository on GitHub might contain multiple workflows, each with a different goal. For instance, one workflow runs tests while another builds and uploads a new app version. They run based on triggered events: The tests’ workflow can run when there’s a new pull request, and the deploy workflow can start once a new Git tag is pushed. The workflow itself contains one or multiple jobs, which in turn consist of one or more steps.

A step can be a regular terminal command, such as running Swift, NodeJS or any other CLI tools and binaries. But to make its CI even more powerful, GitHub allows developers to create their own building blocks and share them with the open-source community. These building blocks are called actions, and your workflows can use these steps besides running one-off script commands. Here’s where GitHub’s platform makes a difference, and the GitHub Marketplace page enables you to search for actions that might fit your needs.

Runners are another important component of GitHub Actions. A runner is a server hosted by GitHub that executes a job of a workflow. Upon execution of a job, a fresh, clean virtual machine is created, running the platform of your choice: Linux, Windows or macOS.

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.