GitLab CI + GitLab Pages + Sphinx で最強のドキュメントビルド環境を構築する

Sphinx + @gitlab でGitLab Pagesに公開するのCIも簡単に導入できるし最強すぎる！！

— としゆき@インフラエンジニア (@Tocyuki) 2019年1月23日

最近、仕事で運用しているサービスのドキュメントをもうWordで作りたくないという思いがすごくてSphinxがよさそうなのでいろいろいじってたらGitLab CI + GitLab Pages + Sphinxが最強のドキュメントビルド環境すぎたのでやり方を説明します。

前提条件

• GitLab.comでアカウント作成済み
• Sphinxで初回ビルドできる環境を構築済み

やること

• リポジトリの作成とクローン
• リポジトリのクローン
• Sphinxでプロジェクトの作成
• .gitlab.ymlを作成し、GitLabへPush後、CI結果を確認
• GitLab Pagesへアクセス

リポジトリの作成とクローン

なんか適当にREADMEだけあるようなリポジトリを作成してクローンしておく

Sphinxでプロジェクトの作成

$ sphinx-quickstart -q -p sphinx-handson -a Tocyuki -v 1.0 sphinx-handson

状態の確認

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
  (use "git add <file>..." to include in what will be committed)

        Makefile
        conf.py
        index.rst
        make.bat

GitLabへPushしておく

$ git add .
$ git commit -m 'Create sphinx-handson project'
$ git push

.gitlab.ymlを作成し、GitLabへPush後、CI結果を確認

以下のページを参考にして.gitlab.ymlを作成する

gitlab.com

image: alpine

pages:
  script:
  - apk --no-cache add py2-pip python-dev
  - pip install sphinx
  - apk --no-cache add make
  - make html
  - mv _build/html/ public/
  artifacts:
    paths:
    - public
  only:
  - master

GitLabへPush

$ git add .
$ git commit -m 'Create .gitlab-ci.yml'
$ git push

CI結果がパスしていることを確認

GitLab Pagesへアクセス

以下のページからGitLab PagesのURLを確認する

画面が正常に表示されることを確認

おわりに

GitLabでCI環境作ってしまえばGitLab Pagesへテスト後自動でデプロイされるしめちゃ便利！
GitHubはデファクトスタンダードだけど、GitLabですべて完結できるのは大きいなぁと感じました！

今後はGitLabを中心に使っていこうかなー。

参考情報

今回使用したリポジトリです。 gitlab.com

Sphinxユーザーの会 sphinx-users.jp