Symfonyのドキュメント にいつもお世話になっていますのでコントリビュートしたいなと思い開発環境を整えましたので参考にした記事や考えたことなどを書き留めておきます。
SymfonyのドキュメントもSymfonyのコードと同様にGitHubで管理されています。
2020/07/12 いただいたコメントの内容を反映しました。ありがとうございます。
まずはライセンスを確認
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 追記 --------------------------------
コメントで peaceiris/actions-gh-pages という便利なGitHub Actionを紹介していただきました。
deploy keyの設定と公開ディレクトリ内のファイルをcommit/pushをしてくれます。
不要なファイルの削除やJekyllの無効化などデフォルトで使いやすいような設定にしていただいているのでありがたいです。
READMEもわかりやすく丁寧に記載いただいており、CNAMEの設定や外部リポジトリへのpushなど今後活用したい機能が多々ありました。
追記ここまで ----------------------------------------
作成したファイルは以下
https://github.com/okazy/symfony-docs/pull/1/files
# プルリクのマージ時など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 ブランチにプルリクを取り込むと自動でページが更新されます！
出来上がったページはこちら。
ちゃんと翻訳していければドメインの取得とかもしたいですね。
日本でも Symfony を盛り上げていきましょう！
プルリク等もお待ちしています。
ではまた。