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

# はじめに

この記事では、`GitHub Actions`のワークフローを使った以下の処理について、書きます。
* [dlang.org](https://dlang.org/)（D言語公式サイト）をビルドします。
* ビルド結果（静的コンテンツ）を`GitHub Pages`へ自動的に反映します。

# GitHub Actions

[GitHub Actions](https://github.co.jp/features/actions)は、[GitHub](https://github.com/)が提供する CI / CD サービスです。
ソフトウェアワークフローを簡単に自動化できます。
パブリックリポジトリでの利用であれば、無料で利用できます。

# GitHub Pages

[GitHub Pages](https://docs.github.com/ja/pages)は、`GitHub`が提供するサービスで、静的コンテンツをインターネット上に公開することができます。
取り扱えるのが静的コンテンツだけですが、こちらも無料で手軽に利用できます。

# dlang.orgをビルドするとは

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

# 実際にやってみる

以下の通りに進めます。

* [D言語公式リポジトリ](https://github.com/dlang/dlang.org)から、個人のリポジトリにフォークする。
* [フォークしたリポジトリ](https://github.com/devmynote/dlang.org)に、[ワークフロー定義ファイル](https://github.com/devmynote/dlang.org/blob/master-jp/.github/workflows/buildwebjp.yml)を追加する。
* ワークフローで、静的コンテンツを生成する。
* `GitHub Pages`を設定して、静的コンテンツを公開する。

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

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

https://qiita.com/morioka1206/items/6f777c060b88f4a7f3ce

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

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

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

``` 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](https://github.com/actions/checkout)は、リポジトリからチェックアウトするためのアクションです。
`dlang.org`の静的コンテンツをビルドするには、`dlang.org`の他に`dmd`、`phobos`、`druntime`リポジトリも必要です。
あわせてチェックアウトします。

## run

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

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

``` text : フォルダ構成
/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](https://github.com/peaceiris/actions-gh-pages)は、静的ファイルをデプロイするためのアクションです。
`dlang.org`の静的コンテンツは、`./dlang.org/web/`に生成されます。これを`web-jp`ブランチにデプロイします。

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

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

``` yaml:
on:
  push:
    branches: [ master-jp ]
```

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

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

![a1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/675901/bd937851-3081-d849-13e7-2455098909ef.png)

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

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

## 日本語翻訳例

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

![a1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/675901/4db254ae-6fbe-ffb9-f4d7-657846637351.png)

# GitHub Actionsでの実行結果

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

[<img src = "https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/675901/0363e249-e52d-8d08-ffda-c686c9d34bf7.png">](https://devmynote.github.io/dlang.org/)

[<img src = "https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/675901/0aca0a09-d44e-7014-b712-4137beb4fd79.png">](https://devmynote.github.io/dlang.org/spec/spec.html)

[<img src = "https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/675901/f7edde3f-638e-d0e9-1374-f76f74c2af28.png">](https://devmynote.github.io/dlang.org/spec/function.html)

https://devmynote.github.io/dlang.org/

# 終わりに

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

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

https://dlang.org/spec/ddoc.html