Edited at

travis-sphinxでGithub PagesにSphinxドキュメントを公開してみる

More than 1 year has passed since last update.


概要

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メニューから設定を行います。

github-settings.png

Personal Settings > Personal access tokensメニューを開き、「Generate new token」よりアクセストークンを取得します。

アクセストークンのscopesはpublic_repoを選択しておけば問題ありませんでした。

personalaccesstoken.png

Travis CI側のプロジェクトのSettingsより、環境変数にGH_TOKENを作成し、Githubで取得したアクセストークンを設定します。

travisci-settings.PNG


.travis.ymlの作成

今回は以下のようなpython3.5の環境でビルドするような.trais.ymlを作成して試してみました。

スクリプトでは、travis-sphinx buildtravis-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/