目の前に僕らの道がある

勉強会とか、技術的にはまったことのメモ

github pagesをsphinxを使ってwiki的に使う。

いちいちやり方を調べるのがめんどうなので、自分メモ。commit pushが必要ですが、自分wiki立てるのがめんどうならこれくらいで充分かなと。
${USER_NAME}と${REPOSITORY_NAME}は適宜自分の環境に置き換えてください。

準備

あらかじめ、githubにレポジトリを作っておきます。

sphinxsphinx-to-githubをインストールしておきます。pythonはpythonbrewなりシステムのなり、どっかから適当にインストールしてください。

pip install sphinx
pip install -e "git+git://github.com/michaeljones/sphinx-to-github.git#egg=sphinx-to-github" 

プロジェクトの作成

いつものようにgitのローカルレポジトリを作成し、sphinxの雛形を作成します。

git init
sphinx-quickstart
# いろいろ聞かれますが、下記の質問以外は適当に答えます。
# > Separate source and build directories (y/N) [n]: y

source/conf.pyを書き換えてextentionを使うようにします。

extensions = ['sphinxtogithub']
sphinx_to_github = True
sphinx_to_github_verbose = True

自身のレポジトリをsubmoduleとしてレポジトリ内に置くため、いったんここでpushします。

git add .
git commit -m 'init commit'
git remote add origin git@github.com:${USER_NAME}/${REPOSITORY_NAME}.git
git push -u origin master

gh-pagesブランチの作成

gh-pagesブランチは実際に表示させるhtmlを置くブランチです。まず、既存のファイルをいったん消してpushします。

git checkout -b gh-pages
git rm -r *
git commit -m 'init gh-pages'
git push -u origin gh-pages

自身をサブモジュールとしてレポジトリに配置

ブランチの移動をせずに、htmlページを反映させるためにbuild/html以下をgh-pagesに設定します。
これにより、htmlを生成した後build/html以下でcommit & pushするだけで、github pagesに反映することができます。

git checkout master
git submodule add git@github.com:${USER_NAME}/${REPOSITORY_NAME}.git build/html

cd build/html/
git checkout gh-pages
cd -
git add build/html
git commit -m 'add gh-pages as submodule'

htmlの生成

いったんここまで完成すれば、後はソースファイルをいじって下記の手順を繰り返すだけです。
ディレクトリ移動してcommit & push するのが少しめんどうですが、ブランチ切り替えるよりはましかなーと言った感じです。
何か他に良い方法があれば教えてください。

#html生成
make html

cd build/html/
git add .
git commit -m 'make simple sphinx pages'
cd -

git add build/html
git commit -m 'update gh-pages'
git push origine gh-pages

cd build/html
git push origine master

これで、下記のページを確認すれば生成したhtmlが表示されているはずです。反映まで少し時間がかかることもあります。

  • http://${USER_NAME}.github.com/${REPOSITORY_NAME}/