How to automate DocC documentation hosting with Github Pages

DocC is a toolset designed specifically for documenting Swift frameworks and packages. This article talks about automating building, exporting and hosting documentations using GitHub workflows and GitHub hosting.

Photo by Roman Synkevych on Unsplash

Prerequisites

• A library thats well documented according to DocC syntaxes and standards.
• Basic Github workflow setup.

Github workflow Steps

Create a workflow file (.yml) inside Project/.github/workflows/ folder and follow the below steps to build the workflow.

1. Checkout to the branch

- name: Checkout 🛎️
  uses: actions/checkout@v3

actions/checkout@v3 is a GitHub action that allows you to fetch the source code or repository into your workflow's workspace. It creates a shallow clone of the repository, including only the most recent commit, for improved performance. You can use it to checkout a specific commit, branch, or tag from a remote repository and make it available for subsequent steps in your workflow.

2. Select required Xcode version

- name: Force Xcode 13.3.1
  run: sudo xcode-select -s "/Applications/Xcode_13.3.1.app"

sudo xcode-select is a command used on macOS to manage the location of Xcode command line tools. It allows you to set the default Xcode installation, install the command line tools, or verify their installation. Using sudo grants administrative privileges for making system-level changes.

3. Install CocoaPods (optional, only if required)

- name: pod install
  run: bundle exec pod install

4. Build DocC documentation

swift package resolve;

xcodebuild docbuild -workspace 'Project.xcworkspace' -scheme Project -derivedDataPath /tmp/docbuild -destination 'platform=iOS Simulator,name=iPhone 12';
          
echo "Archiving documentation..."
          
$(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphonesimulator/Project.doccarchive \
            --output-path docs \
            --hosting-base-path '';
            
echo "** Archived documentation**"
          
echo "<script>window.location.href += \"tutorials/table-of-contents\"</script>" > docs/index.html;

When you execute xcodebuild docbuild -workspace, Xcode will analyze your project or workspace and generate the associated documentation. This documentation typically includes API references, code comments, and other relevant information about the project.

When you execute $(xcrun --find docc) process-archive, you are instructing the docc tool to process a documentation archive. The documentation archive typically contains the necessary files and metadata required to generate documentation for a particular project or framework.

It’s worth noting that the specific behavior and available options for the xcodebuild docbuild command may vary depending on the Xcode version and the structure of your project or workspace. It's recommended to consult the Xcode documentation or use the xcodebuild command-line tool's help option (xcodebuild -help) for more details on the available options and how to use them.

5. Upload Artefacts

- name: Upload artifact
  uses: actions/upload-pages-artifact@v1
  with:
    # Upload only docs directory
    path: 'docs'

The actions/upload-pages-artifact action is designed to upload a directory of files as an artifact to the GitHub Pages branch. It is commonly used in CI/CD (Continuous Integration/Continuous Deployment) workflows to generate documentation, build websites, or any other static content that needs to be published to GitHub Pages.

By including this action in your GitHub Actions workflow, you can generate a directory of files and then use the actions/upload-pages-artifact action to upload those files to the appropriate branch of your repository, which is typically the gh-pages branch used for GitHub Pages.

6. Deploy to Github Pages

- name: Deploy to GitHub Pages
  id: deployment
  uses: actions/deploy-pages@v1

actions/deploy-pages@v1 is a GitHub action that helps deploy static websites or web applications to GitHub Pages. It automates the process of pushing built artifacts to a specified branch or folder within the repository, making it easier to publish your site on GitHub Pages.

Full Github workflow

name: Deploy DocC Documentation to Github Pages
on:
  # Runs on pushes targeting the master branch
  push:
    branches: ["master"]

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true
  
jobs:
  # One deployment deploy job since we're just deploying
  deploy:
    environment:
      # Must set to this for deploying to GitHub Pages
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: macos-12
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Force Xcode 13.3.1 
        run: sudo xcode-select -s "/Applications/Xcode_13.3.1.app"
      - name: pod install
        run: pod install
      - name: Build DocC
        run: |
          swift package resolve;
          
          xcodebuild docbuild -workspace 'Project.xcworkspace' -scheme Project -derivedDataPath /tmp/docbuild -destination 'platform=iOS Simulator,name=iPhone 12';
          
          echo "Archiving documentation..."
          
          $(xcrun --find docc) process-archive \
            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphonesimulator/Project.doccarchive \
            --output-path docs \
            --hosting-base-path '';
            
          echo "** Archived documentation**"
          
          echo "<script>window.location.href += \"tutorials/table-of-contents\"</script>" > docs/index.html;

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload only docs directory
          path: 'docs'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1