Symfony のドキュメントを GitHub Actions で GitHub Pages にホスティングしてみた

[Symfonyのドキュメント](https://symfony.com/doc/current/index.html) にいつもお世話になっていますのでコントリビュートしたいなと思い開発環境を整えましたので参考にした記事や考えたことなどを書き留めておきます。

SymfonyのドキュメントもSymfonyのコードと同様にGitHubで管理されています。

**2020/07/12 いただいた[コメント](https://qiita.com/okazy/items/8e55824f767a854a8dd0#comment-fd7c3ee7a8df6a051019)の内容を反映しました。ありがとうございます。**


## まずはライセンスを確認

**Creative Commons Attribution-ShareAlike 3.0 Unported**　https://creativecommons.org/licenses/by-sa/3.0/

簡単にいうと改変と再配布はOK、ただしクレジットの表記とライセンスの継承はしてねといったところです。
ライセンス的にはホスティングしても問題なさそうです。
本記事も上記ライセンスに従います。


## ローカルでの起動

README に記載いただいている Docker の方法で問題なく起動できました。
https://github.com/symfony/symfony-docs#docker

開発への参加のしやすさはコントリビュートの難易度に直結しますのでとても重要ですね。
ちなみにローカルのpythonでビルドしてみようとしましたが時間がかかりそうだったので諦めました。


## GitHub Pages でのホスティング

日本語へ翻訳していきたいと思っていたのでホスティングしようと考えました。
どうやらドキュメントは reStructuredText というマークアップ言語で書かれているようです。
Jekyll を利用してマークダウンのドキュメントを GitHub Pages にホスティングしたことがありました。
サーバのメンテナンスはしたくなかったので GitHub Pages で同じように公開できないか調べてみました。

reStructuredText とマークダウンの書き方が似ているからと言って Jekyll では変換できなさそうです。
一度 Html にビルドしてしまえばホスティングはできそうです。

GitHub Pages の設定方法は以下の記事が参考になります。

**GitHub Pages を使った静的サイトの公開方法が、とても簡単になっていた**
https://www.tam-tam.co.jp/tipsnote/html_css/post11245.html

開発中にわざわざビルドしてコミットしてプッシュなんてしたくないので、 CD を設定して勝手にデプロイされるようにしたいです。
また、Symfonyのドキュメントの本家と差分が出過ぎても嫌なので master ブランチにはコンパイルされたファイルはコミットせず、gh-pages ブランチでホスティングするようにします。


## GitHub Actions

リポジトリ内に GitHub Actions の CI のワークフローがあったので設定してみました。
https://github.com/symfony/symfony-docs/blob/master/.github/workflows/ci.yaml
シンプルでわかりやすい内容でしたのでこちらを参考にさせていただきましょう。
（Docker はPython2 系でしたが GitHub Actions は Python3 系ですね）

以下のサイトが大変参考になりました。

**GitHub Actionsを用いてGitHub Pagesへのデプロイを自動化する**
https://sphinx-users.jp/cookbook/githubaction/index.html

紹介されている手順に従って Deploy keys と Secrets を登録しておきます。

CI は push とプルリク時にも実行したいけど、デプロイはプルリクのマージ時に実行したいので、ワークフローを分けて作成することにしました。

**2020/07/12 追記 --------------------------------**
[コメント](https://qiita.com/okazy/items/8e55824f767a854a8dd0#comment-fd7c3ee7a8df6a051019)で `peaceiris/actions-gh-pages` という便利なGitHub Actionを紹介していただきました。

https://github.com/peaceiris/actions-gh-pages

deploy keyの設定と公開ディレクトリ内のファイルをcommit/pushをしてくれます。
不要なファイルの削除やJekyllの無効化などデフォルトで使いやすいような設定にしていただいているのでありがたいです。

READMEもわかりやすく丁寧に記載いただいており、CNAMEの設定や外部リポジトリへのpushなど今後活用したい機能が多々ありました。
**追記ここまで ----------------------------------------**

作成したファイルは以下
https://github.com/okazy/symfony-docs/pull/1/files

```yaml:.github/workflows/cd.yaml
# プルリクのマージ時などjaブランチが変更されたタイミングで実行
on:
    push:
        branches:
            - ja

name: CD

jobs:
    deploy:
        name: Deploy

        runs-on: ubuntu-latest

# push -> CD -> push -> ... のループを避けるためコミットコメントを見て自動コミットかどうかを判断

        if: "!contains(github.event.head_commit.message, 'deploy:')"

        steps:
            -   name: "Checkout"
                uses: actions/checkout@v2

            -   name: "Set up Python 3.7"
                uses: actions/setup-python@v1
                with:
                    python-version: '3.7' # Semantic version range syntax or exact version of a Python version

            -   name: "Display Python version"
                run: python -c "import sys; print(sys.version)"

            -   name: "Install Sphinx dependencies"
                run: sudo apt-get install python-dev build-essential

            -   name: "Cache pip"
                uses: actions/cache@v2
                with:
                    path: ~/.cache/pip
                    key: ${{ runner.os }}-pip-${{ hashFiles('_build/.requirements.txt') }}
                    restore-keys: |
                        ${{ runner.os }}-pip-

            -   name: "Install Sphinx + requirements via pip"
                run: pip install -r _build/.requirements.txt

            -   name: "Build documentation"
                run: make -C _build SPHINXOPTS="-nqW -j auto" html

# ここまでは ci.yaml の内容とほぼ同じ

# peaceiris/actions-gh-pages を利用して gh-pages ブランチを更新
            -   name: "Deploy GitHub Pages"
                uses: peaceiris/actions-gh-pages@v3
                with:
                    deploy_key: ${{ secrets.MY_ACTIONS_DEPLOY_KEY }}
                    publish_dir: ./_build/html
```

### 注意点1: 無限ループを避ける

GitHub Actions 内で push しているので下手をするとまたワークフローが実行され無限ループに陥る可能性があります。
- コミットメッセージによる自動コミットかのチェック
- ワークフローをcommitしない （2020/07/12 追記 `peaceiris/actions-gh-pages` を利用）
の2個の対策を入れておきました。

### 注意点2: Jekyll の無効化

GitHub Pages のデプロイ時にはデフォルトで Jekyll が実行されます。
Jekyll が実行されるとcssや画像などの '_' から始まるディレクトリのリソースがブラウザから読み込めなくなってしまいます。
なので `.nojekyll` ファイルを設置して Jekyll が実行されないようにしています。
（2020/07/12 追記 `peaceiris/actions-gh-pages` ではデフォルトで Jekyll が無効になっています。）

### 注意点3: push は Force の力を借りる

gh-pages ブランチはあくまでデプロイ用と割り切り Force の力を借りることにしました。
（2020/07/12 追記 `peaceiris/actions-gh-pages` でも Force してくれている）

## デプロイ完了

これで ja ブランチにプルリクを取り込むと自動でページが更新されます！
出来上がったページはこちら。

https://okazy.github.io/symfony-docs/index.html

ちゃんと翻訳していければドメインの取得とかもしたいですね。
日本でも Symfony を盛り上げていきましょう！
プルリク等もお待ちしています。

ではまた。