DocC Tutorial for Swift: Automating Publishing With GitHub Actions

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).

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!