GitLabでドキュメントのビルドとホスティング
完全に思いつきで、GitLabでドキュメントをgit管理してCIでビルドしてGitLab Pagesで表示する、というのをやってみました。
GitLabはGitHubみたいなサービスです。 （というかGitHubクローンで、以前はあまりにも似過ぎてたためになんか色々あったらしい、というウワサをどこかで目にしたような・・・？） （そのせいかわかりませんが、プルリクエストはMerge Requestという名前のようですね・・・）
GitHubでも似たようなことはできますが、
- Travis CI（などのCIサービス）を使ってgh-pagesブランチにプッシュする
- Read the Docsを使ってそっちでビルド＆表示
などいずれにしろ別サービスとの連携が必要になってしまいます。 ローカルでhtmlを作って自分でpushすることもできますが、それは何か少し負けた気がするので却下です。
GitLabはCIもGitLab上で回せるので、
まで一つのサービスで完結できました。
GitLabのアカウントはGitHubの認証で簡単に作れるので、例えば英語ドキュメントの翻訳プロジェクトなどでは使ってみるのもありではないでしょうか。
ということで簡単に手順を紹介します。
ちなみに、思いついてからGitLabのアカウントを作るような状態でしたが、一時間足らずでリポジトリを作ってページを表示するまでできました。
- 試しに作ったリポジトリ: https://gitlab.com/miyakogi/test-doc
- 出力されたページ: https://miyakogi.gitlab.io/test-doc/index.html
リポジトリの作成
ログインして「New Project」または右上の「＋」ボタンを押せば作れます。 適当にプロジェクト名などを入力するだけです。
プロジェクトが作られたらローカルにcloneしておきます。
ドキュメントの用意
今回は試しにMkDocsを使いましたが、sphinxなどもコマンドが変わるだけで同じように使えると思います。 MkDocsはsphinxのようなドキュメントがmarkdownで書けるものです。
GitLabのドキュメントにはJekyllや生HTML、HugoやHexoなどの例が紹介されているので、普通の静的サイトジェネレータはだいたい使えるのだと思います。 まぁHTML置くだけですからね・・・ （とはいえPythonの例が一つもないとはどういうことなんですかね・・・）
インストールはpip install mkdocsです。
mkdocs new gitlab-testでプロジェクトを作ったのですが、gitlab-testディレクトリ以下に作られてしまったのでmv gitlab-test/* ./でリポジトリのルートにファイルを全部移動させました。
このあたりはGitLabは関係ないので好みでいいと思います。
そしてindex.mdを適当に編集し、mkdocs buildでビルドするとsiteディレクトリ以下にhtmlなどが作られます。
ローカルで確認する場合はmkdocs serveでhttpサーバ（tornadoっぽい）が立ち上がるのでhttp://localhost:8000/にブラウザでアクセスすると表示されます。
ドキュメントが作れることを確認したら、いよいよGitLabの方の設定に入ります。
GitLab CIの設定
リポジトリのルートに.gitlab-ci.ymlというyaml形式の設定ファイルを作り、git add .gitlag-ci.ymlしてコミット＆プッシュすればサーバー上で実行されます。
設定ファイルは以下のようにした所うまくいきました。
image: python: 3.5 pages: stage: deploy script: - pip install mkdocs - mkdocs build -d public artifacts: paths: - public only: - master
imageでは使用するdockerのイメージを指定するようです。
始め「デフォルトでもpipくらい使えるだろ〜」とimageを指定しなかった所、pipがなくてエラーになりました。
デフォルトではruby: 2.1のイメージが使われるようです。
apt-getでインストールすればよかったのかもしれませんが、今後使うかもしれないPythonのイメージを指定してみました。
pagesというのがジョブの名前です。
静的ページをホストする時はpagesという名前にする必要があるようです。
stage: deployはなくてもいいかも？
script:以下が実際に実行されるコマンドです。
MkDocsをインストールした後にビルドしているだけですが、ここで出力先をpublicというディレクトリに指定しています。
その後にartifacts: paths:でパスを指定しているのでディレクトリ名は何でもいいのかと思ったのですが、デフォルトのsiteに出力してpathsにsiteを指定してもダメでした。
ここが唯一のハマりポイントでした。
というわけで出力先はpublicに。
これをプッシュするとすぐにサーバー上でビルドが実行されます。
同一サービス上で実行されるので、GitHub + Travis CIよりやはり実行開始は早いです。
あと、.gitlab-ci.ymlの記述がおかしいとすぐにエラーを表示してくれます。
プッシュ直後はこんな感じです。
無事にビルドできれば、https://ユーザー名.gitlab.io/プロジェクト名にアクセスすることでページが表示されるはずです。
感想
実際に使ってみてよかった点は、CIも静的ページのホスティングも単一サービスで完結しているので設定が楽、ということに尽きると思います。 思いついてから一時間足らずで完了しましたからね。 この記事書くほうが時間かかってます。 あと、無料でプライベートリポジトリも使えますし。
一方で不満だった点は、サーバーのレスポンスが（GitHubと比較して）遅い感じがするところでしょうか。 これはサーバーの立地や時間帯（日本時間金曜22時頃 = ヨーロッパの金曜昼 = アメリカ東海岸で金曜朝）のせいかもしれません。 レスポンスが悪い上にファイル一覧のUIに慣れていないので、普通の開発プロジェクトでソースコードを閲覧するのはちょっと厳しいという印象でした。
逆に、ファイルをあちこち移動しない翻訳プロジェクトなどでは候補としてありかもしれません。 MarkdownファイルをWeb上から編集して、そのままコミット→ビルドというのもできました。 もちろんコミット権限が必要ですが、権限がなくてもそのままMerge Requestが出せるのではないでしょうか（未確認）
本質的ではないのですが、いくらGitLab上でコミットしても（当然）GitHubに草が生えないのはモチベーション的に問題な気がします。 これ実はすごく深刻な問題だと思うので、GitLabさんは下克上したかったらなんとかした方がいいと思います（無茶振り）。
以上、あまりGitLabの情報を見かけなかったので思いつき＆勢いで記事にしてみました。 参考になれば幸いです。
