Github PagesでSphinxの出力をホストする
難しそうな気配を感じて二の足を踏んでいたが意外とあっさりだったのでメモ。
1. Sphinxの出力ファイルを単に配置するだけでは_staticなどが無視されて悲しくなるので、github pages に Sphinx で生成したドキュメントを公開する。 - kuma8の日記を参考に、sphinxtogithubをインストールする。(←意外とあっさりポイント1)
2. make cleanしてmake htmlし直して問題ないことを確認。
3. 今回HTMLを生成するためのsphinxのコードは今このリポジトリで管理されているので、この手元のワークツリーを空っぽにしたりとかしたくない。そこでリポジトリ内で同じリポジトリをcloneする。ちなみにいまプロジェクトルートがlearn_languageで、その中のsphinxdocってディレクトリの中にいる。
$ git clone https://github.com/nishio/learn_language.git
4. 空っぽのブランチを作る。rm .git/indexみたいなバッドノウハウ臭漂う方法を紹介しているサイトもあるようだが、あまりに臭いのでスルーして公式サイトCreating Project Pages manually · github:helpの通りにやる。(←意外とあっさりポイント2)
$ cd learn_language $ git checkout --orphan gh-pages
5. 空っぽのブランチができた。僕はzshでgitの状態を表示しているので、なんかaddされてる状態になっていることに気づいた。
learn_language[*gh-pages*added]$ git status # On branch gh-pages # # Initial commit # # Changes to be committed: # (use "git rm --cached <file>..." to unstage) # # new file: README.rst # learn_language[*gh-pages*added]$ ls README.rst
ああ、最初のコミットをする寸前の状態になっているのね。じゃあ消そう。
$ git rm -f README.rst
6. 上のディレクトリでSphinxのビルドをして、出力をコピー、addしてcommitしてpush。
$ cd .. $ make html $ cp -r _build/html/* learn_language $ cd learn_language $ git add . $ git commit -m "..." $ git push origin gh-pages
7. http://nishio.github.com/learn_language/を確認する。うん、問題なさげ。(←意外とあっさりポイント3)
8. 外のリポジトリに戻るとさっきgit cloneしたディレクトリがuntrackedになっているので、.gitignoreに追加しておく。
sphinxdoc[*develop*untracked]$ git status # On branch develop # Your branch is ahead of 'origin/develop' by 1 commit. # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # learn_language/ nothing added to commit but untracked files present (use "git add" to track) sphinxdoc[*develop*untracked]$ echo learn_language >> .gitignore sphinxdoc[*develop*modified]$
9. SphinxのMakefileにこんなターゲットを追加しておく
deploy:
cp -r _build/html/* learn_language
cd learn_language; \
git add .; \
git commit -v; \
git push origin gh-pages10. ちょこっと書き換えてみてmake htmlしてからmake deployを試してみる。ちゃんとすんなりいった。(←意外とあっさりポイント4)
めでたしめでたし。
