概要
travis-sphinxを利用してみたので、その際の手順を記事として残しておきます。
travis-sphinxはGithubのSphinxのドキュメントをTravis CIでビルドし、gh-pagesブランチにPushするまでを自動化するツールです。
利用方法についてはREADME.mdを参考にしています。
前提
今回は以下のバージョンで動作確認しています。
| ツール | バージョン |
|---|---|
| Python | 3.5.1 |
| Sphinx | 1.4.1 |
gh-pagesブランチの作成
まず、Github Pages用のブランチを作成します。
git checkout -b gh-pages
git rm -rf .
git push --set-upstream origin gh-pages
さらに、gh-pagesブランチにあらかじめ.nojekyllファイルを作成し、pushしておきます。
Githubのアクセストークンを取得
travis-sphinxが、gh-pagesブランチへドキュメントをPushするためにアクセストークンが必要になります。
以下のGithubのアカウントのPersonal Settingsメニューから設定を行います。
Personal Settings > Personal access tokensメニューを開き、「Generate new token」よりアクセストークンを取得します。
アクセストークンのscopesはpublic_repoを選択しておけば問題ありませんでした。
Travis CI側のプロジェクトのSettingsより、環境変数にGH_TOKENを作成し、Githubで取得したアクセストークンを設定します。
.travis.ymlの作成
今回は以下のようなpython3.5の環境でビルドするような.trais.ymlを作成して試してみました。
スクリプトでは、travis-sphinx buildとtravis-sphinx deployを呼び出しておけば、ドキュメントのビルドとPushを行ってくれるようです。
language: python
python:
- "3.5"
before_install:
- wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
- chmod +x miniconda.sh
- "./miniconda.sh -b"
- export PATH=/home/travis/miniconda2/bin:$PATH
- conda update --yes conda
- sudo rm -rf /dev/shm
- sudo ln -s /run/shm /dev/shm
install:
- conda install --yes python="3.5" sphinx
- pip install --user travis-sphinx
script:
- travis-sphinx build --source=example build
after_success:
- travis-sphinx deploy
おわりに
travis-sphinxのREADME.mdを読めば、特につまることなく利用し始められると思いますが、非常に簡単にGithub Pagesへの公開まで自動化できて感動したので使い方をまとめました。
ちなみに、最近、Sphinxにはまっていてテーマを作った際にtravis-sphinxを利用してGithub Pagesにデモドキュメントを公開してみました。
ということで、こちらのテーマもよろしくお願いします。
http://myyasuda.github.io/sphinxbootstrap4theme/