GitHub Actionsを使ったdlang.orgの作り方

はじめに

この記事では、GitHub Actionsのワークフローを使った以下の処理について、書きます。

• dlang.org（D言語公式サイト）をビルドします。
• ビルド結果（静的コンテンツ）をGitHub Pagesへ自動的に反映します。

GitHub Actions

GitHub Actionsは、GitHubが提供する CI / CD サービスです。
ソフトウェアワークフローを簡単に自動化できます。
パブリックリポジトリでの利用であれば、無料で利用できます。

GitHub Pages

GitHub Pagesは、GitHubが提供するサービスで、静的コンテンツをインターネット上に公開することができます。
取り扱えるのが静的コンテンツだけですが、こちらも無料で手軽に利用できます。

dlang.orgをビルドするとは

dlang.org（D言語公式サイト）のソースは、D言語公式リポジトリに公開されています。
リポジトリには、htmlファイルの元になるddファイルが公開されています。
ddファイルからhtmlファイルを生成するには、D言語コンパイラを使ってビルドします。

実際にやってみる

以下の通りに進めます。

• D言語公式リポジトリから、個人のリポジトリにフォークする。
• フォークしたリポジトリに、ワークフロー定義ファイルを追加する。
• ワークフローで、静的コンテンツを生成する。
• GitHub Pagesを設定して、静的コンテンツを公開する。

D言語公式リポジトリからフォークする

フォークについての説明は省略します。以下のリンクを参照してください。
フォークした後に、masterブランチを引き継いだ、master-jpブランチを作成（チェックアウト）します。

リポジトリにワークフロー定義ファイルを追加する

ワークフローの定義は、yaml形式で記載します。
作成したファイルは、以下の通りです。

ワークフローファイルの実装例

.github / workflows / buildwebjp.yml

name: 'Publish web-jp'

on:
  push:
    branches: [ master-jp ]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: 'Download dmd'
      uses: dlang-community/setup-dlang@v1
      with:
        compiler: dmd-latest
    - name: 'Checkout dlang.org'
      uses: actions/checkout@v3
      with:
        path: dlang.org
    - name: 'Checkout dmd'
      uses: actions/checkout@v3
      with:
        repository: dlang/dmd
        ref: v2.100.1
        path: dmd
    - name: 'Checkout phobos'
      uses: actions/checkout@v3
      with:
        repository: dlang/phobos
        ref: v2.100.1
        path: phobos
    - name: 'Checkout druntime'
      uses: actions/checkout@v3
      with:
        repository: dlang/druntime
        ref: v2.100.1
        path: druntime
    - name: 'Make html file'
      run: |
        cd dlang.org
        make -f posix.mak release
    - name: 'Deploy web-jp'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_branch: web-jp
        publish_dir: ./dlang.org/web

actions/checkout@v3

actions/checkoutは、リポジトリからチェックアウトするためのアクションです。
dlang.orgの静的コンテンツをビルドするには、dlang.orgの他にdmd、phobos、druntimeリポジトリも必要です。
あわせてチェックアウトします。

run

runは、GitHub Actions実行環境で任意のコマンドを実行するためのアクションです。

各リポジトリをチェックアウトしたときのGitHub Actions実行環境のフォルダ構成は以下になります。
/home/runner/work/dlang.org/dlang.org/は、ワークフロー作業用フォルダ$GITHUB_WORKSPACEに該当します。

フォルダ構成

/home/runner/work/dlang.org/dlang.org/
├─dlang.org
├─dmd
├─phobos
└─druntime

cd dlang.orgで/home/runner/work/dlang.org/dlang.org/dlang.org/に移動し、make -f posix.mak releaseを実行します。
※dlang.orgが3回続きますが間違いではありません。

peaceiris/actions-gh-pages@v3

peaceiris/actions-gh-pagesは、静的ファイルをデプロイするためのアクションです。
dlang.orgの静的コンテンツは、./dlang.org/web/に生成されます。これをweb-jpブランチにデプロイします。

ワークフローで静的コンテンツを生成する

buildwebjp.ymlにワークフローの実行条件on:が以下の通りに定義されています。
master-jpへのマージ（または、プッシュ）のタイミングでワークフローが実行されます。

on:
  push:
    branches: [ master-jp ]

GitHub Pagesを設定して、静的コンテンツを公開する

リポジトリの「Settings」＞「Pages」を選択するとGitHub Pagesの設定画面が表示されます。
赤枠の通りに設定すれば、web-jpブランチがインターネットへの公開対象になります。

おまけ：アレンジしてみる

公式サイトの情報をそのまま公開しても面白みがないので、この記事では一部日本語翻訳してみました。
masterブランチをチェックアウトして、master-jpブランチを作成します。
master-jpブランチで、公式サイトのソースファイルに手を加えます。

日本語翻訳例

「目次」のソースファイルを翻訳した例です。

GitHub Actionsでの実行結果

ワークフローを実行した結果、以下のように、静的コンテンツが完成しました。
画像をクリックするとリンク先にジャンプします。
まるで日本語版サイトが完成したように見えれば、大成功です。

終わりに

GitHub ActionsとGitHub Pagesを使って、無料でここまでできるとは、便利な時代になりましたね。

D言語によるドキュメント生成機能については、以下に詳しい説明があります。