DocC Tutorial for Swift: Automating Publishing With GitHub Actions

The GitHub Pages URL Format

GitHub Pages can host two types of pages: personal and projects. Personal pages are intended to be your “home” on the web, while project pages can be an open-source project’s showcase.

While personal pages must belong to a repository named <username>.github.io, and the page is accessible at https://username.github.io, project pages work slightly differently. The repository can have any name, and users can find it at https://username.github.io/<repository-name>.

To take that into account, the export command can receive a base path and adjust the routes accordingly. Open — for the last time today — the build script at build-docc.sh. In the second command, where you see the comment, set your repository name in the already present, but empty, hosting-base-path argument:

--hosting-base-path "<your-repository-name>"

This makes your documentation aware of the relative location in which it’s placed on the website when DocC transforms the documentation for publishing.

Moving forward, it’s time to set up your workflow.

Configuring GitHub Actions

All the GitHub Actions configuration you’ll need takes place in the workflow file, so there’s no need to change the Actions settings. All workflow files must reside under the .github/workflows directory. To create one, run the following command:

mkdir -p .github/workflows

Now, create the YAML file you’ll use to define your workflow:

touch .github/workflows/docc.yml

Defining the Workflow File

Open the file you just created with your text editor. Copy the lines below and paste them into this new file. Make sure your text editor keeps the space indentation instead of replacing them with tabs. YAML relies on the spaces and the indentation to validate the content and its structure.

#1
name: docc

#2
on:
  push:
    branches: [main]
  workflow_dispatch:

#3
permissions:
  pages: write
  id-token: write
  contents: read

Here’s what this file describes so far:

1. The name of this workflow.
2. The events that will trigger running this workflow. The push trigger will work when new commits are pushed to the main branch. Adding workflow_dispatch allows manually triggering the workflow from the GitHub Actions UI.
3. Set permissions for the GitHub token running the Action to allow deployment to GitHub Pages, and read permissions for checking out the repository content.

A workflow contains one or more jobs. The first stage of the workflow is running the script you prepared above. To configure the job to do so, add the following code:

#1
jobs:
  build:
    #2
    runs-on: macos-12
    #3
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      #4
      - name: Run Build Docs
        run: ./build-docc.sh
      #5
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: .docs

It might be a lot, but breaking it down piece by piece makes it easier to understand:

1. Declare the jobs map, and start with the build job.
2. Because the script relies on xcrun and Xcode, you’ll need a macOS runner. When using DocC as a Swift package plugin, you can use a Linux machine instead.
3. One or more steps make up a job. Declare the list of steps, and start by checking out the repository taking only the last commit. Therefore, the fetch-depth option is set to 0.
4. After checking out the repository, run the build-docc.sh script.
5. Use the actions that GitHub provides: one for configuring pages and another for uploading the contents that the script will generate and place under .docs. Notice how this is the same directory you set in the last line.

You’re almost done! Now, you need to define a job to deploy what the build job generated.

Publishing to GitHub Pages via Actions

Still in the docc.yml file, add the lines below. Pay attention to the fact that the deploy key should have the same indentation as the build key from the previous snippet.

  #1
  deploy:
    #2
    runs-on: ubuntu-latest
    #3
    needs: build
    #4
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2 
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

Here’s what these lines mean:

1. Define the deploy job.
2. Because Xcode isn’t necessary anymore, you can choose a Linux runner.
3. The previous job, build, created and uploaded the artifacts. So, add a dependency on that job, meaning that this one will only run when the first has finished.
4. Declare a single step for this job based on the official actions/deploy-pages Action. Set the environment variables it requires.

It’s finally time to test it all!

Running the Workflow on GitHub Actions

If you haven’t yet created your repository locally, run:

git init

As this is a new repository, all your changes are file additions. After staging them, create an initial commit. Then, add the GitHub remote. Replace your username and the repository name before running this command:

git remote add origin https://github.com/<your-username>/<your-repository-name>.git

Create the main branch, and push your changes:

git branch -M main && git push -u origin main

After pushing it to GitHub, open your repository page, and go to the Actions tab. In the list, you’ll see the Action you just created, within a few moments, in the queued state.

In some cases, the Action might get stuck in the queued state. If that’s the case, you’ve already defined the workflow_dispatch event in the workflow, which allows manually triggering the Action.

After moving from the queued to the running state, click the workflow run in the list to see more details:

Notice how, in the image above, there’s a line between the build and deploy. It represents the dependency of the deploy job on the build job.

After a few minutes, both jobs should be complete:

As you can see, both jobs have green check marks, making the run itself a successful one. Under deploy, you’ll see a link. Clicking it will take you to https://<your-username>.github.io/<repository-name>, and the browser will display the documentation you worked so hard to publish:

Where to Go From Here?

You can download the completed project files by clicking Download materials at the top or bottom of the tutorial.

Congratulations on reaching the end of this tutorial! It included many steps: writing a shell script, creating a repository, enabling GitHub Pages on it, defining your workflow file and running it. If you made it here, it means you learned and acquired new skills.

If you already feel the superpowers of automating your processes, you might want to expand your knowledge in the CI/CD space, deepen your expertise in GitHub Actions, and also in technologies or services that host static content and make its distribution even faster with content delivery networks (CDNs). Here’s what you could do next:

• Wrap your frequently used steps into a shareable Action of your own.
• Connect to the web: Automate calling your workflows via webhooks and also call external webhooks from your workflow steps.
• Automate generation of Swift code that compiles on Linux, using the DocC Swift Package Manager plugin, instead of relying on Xcode and macOS. By doing so, you don’t need to use the macOS runners. The Linux runners will be enough, which is a positive factor since they consume fewer credits than the macOS ones.
• Publish your documentation to other services, such as Netlify, which provides a CDN on top of hosting.

We hope you enjoyed this tutorial, and if you have any questions or comments, please join the forum discussion below!