🛠️

Enterprise PrivateリポジトリでSwift DocCのドキュメントをGitHub Pagesにデプロイする

2024/01/10に公開

GitHub Actions

Swift Package Manager

DocC

tech

Swift-DocC Pluginを使えば自作のSwift PackageのドキュメントをWebページとして簡単かつ高品質に作ることができます。また、そのWebページをGitHub Pagesでデプロイすることも可能になっています。

具体的な方法については公式のドキュメントがあります（これ自体がSwift DocCで作られ、GitHub Pagesにデプロイされている）が、会社のGitHub Enterprise環境で社内Privateリポジトリでドキュメントを作ろうとして躓いたので備忘録をまとめます。

流れ

自作Swift Packageを用意（GitHubにリポジトリも用意）
Swift DocCの記法に従いコードコメントでドキュメントを記述

Package.swiftのdependenciesにswift-docc-pluginを追加

Package.swift

dependencies: [
    .package(
        url: "https://github.com/apple/swift-docc-plugin.git", 
        exact: "1.3.0"
    )
],

GitHubリポジトリのSettingsでPagesを開き、Build and deploymentのSourceをGitHub Actions (Beta)に指定

DocCをデプロイする用のワークフローをGitHub Actionsとして追加

.github/workflows/docc_deploy.yml

name: Deploy DocC

on:
  workflow_dispatch: #適宜指定

#更新ワークフローの実行が重なったら古い方をキャンセルする   
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: macos-13
    env:
      DEVELOPER_DIR: /Applications/Xcode_15.1.app/Contents/Developer

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      # リポジトリのルートディレクトリにPackage.swiftがあることを前提としている
      - name: Build DocC
        run: |
          swift package --allow-writing-to-directory ./docs \
            generate-documentation \
            --target [パッケージ名] \
            --disable-indexing \
            --transform-for-static-hosting \
            --output-path ./docs

      # Artifactにアップロードされた成果物がGitHub Pagesにデプロイされる
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: docs

  deploy:
    runs-on: ubuntu-latest
    needs: build
    permissions: # GitHub Pagesへのデプロイに必要な権限
      pages: write
      id-token: write
    environment: 
      name: github-pages
      url: "https://[Organization名].github.io/[リポジトリ名]/documentation/[パッケージ名の小文字表記]/"

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

docc_deploy.yml実行

これでhttps://[Organization名].github.io/[リポジトリ名]/documentation/[パッケージ名の小文字表記]/にドキュメントがデプロイされます。

注意点

Publicリポジトリの場合ビルドコマンドのオプションで--hosting-base-pathを指定しますが、Privateリポジトリの場合はつけない
permissionsの指定がないとGitHub Actionsがデプロイできない
実際にドキュメントがホスティングされるURLが特殊なので注意
- リポジトリ名は大文字小文字を区別する
- documentation/の後のパッケージ名は小文字表記である必要がある(?)
もしもデフォルトブランチ以外でドキュメントデプロイの作業をしようとした場合、そのブランチがEnvironmentsのprotection ruleに含まれている必要がある

流れ

注意点

Discussion