github のプロジェクトにSphinxドキュメントを良さげな感じにおきたい 其の一

大分前にこんな感じの事をしたので、その時の覚え書き。githubで管理されているOSSなんかでは良く、下記のようなURLでドキュメントを公開しているプロジェクトがありますよね。

http://[account_name].github.com/[repository_name]/
  • account_name(アカウント名)がサブドメイン
  • repository_nameが対象のリポジトリ名

これどうやってんだろう?と思ってたのがきっかけです。以下手順を見てみましょう。前提として既にgithub上にリポジトリを持っていることとします。

GitHub Pagesを用意する

そもそも、上のURL体系でページが参照できるのは、Github Pagesのおかげのようなので、まずはこれを用意します。Github Pagesを利用していないリポジトリで上のようなURLにアクセスすると、ご丁寧にページの作り方が書いてあります。

f:id:tell-k:20120118180957p:plain

この通りにやってみましょう。

$ cd /path/to/repo-name
$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx
$ echo "My GitHub Page" > index.html
$ git add .
$ git commit -a -m "First pages commit"
$ git push origin gh-pages

これを実行をすると何が起こるか簡単に言うと、本当に中身が空っぽなブランチを作ってるという事らしいです。

ブランチを切り替える

この時にブランチの状況はこのように masterとgh-pages の二つが作成されていて、カレントは「gh-pages」に向いています。

$ git branch
* gh-pages
  master

「ls」を実行すると、index.htmlだけが存在しているのが確認できます。

$ ls 
index.html

この状態で、最初のURL体系でアクセスすると、"My GitHub Page" が見れると思います。やったね。

f:id:tell-k:20120118184758p:plain

もとの master ブランチに移動したい時は下記のようにすると戻れます。

$ git checkout master
Switched to branch 'master'

$ git branch
  gh-pages
* master

Sphinx ドキュメントを置いてみる

さて index.html だけでは寂しいので、Sphinxのドキュメントを「gh-pages」に置いてみましょう。

# とりあえずindex.htmlは消してpushしておく
$ git checkout gh-pages
$ git rm index.html
$ git commit -m 'remove index.html'
$ git push origin gh-pages

# sphinxドキュメントを作成する
$ sphinx-quickstart

# 後は指示にしたがってお好みで作りましょう。
# ここでは、build ディレクトリと sourceディレクトリを分けた設定にしています。
$ tree
.
├── Makefile
├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

Sphinxのプロジェクトが出来たらmake html しましょう。make html すると「build/html」にHTMLファイル群が作成されますが、それをそのまま gh-pagesにpushしてもドキュメントは表示されません。

gh-pages ブランチのルートが、Web上で表示する時のドキュメントルートになっている感じなので、作ったファイルをgh-pagesのルートにコピーしてやります。そしたらaddしてpushしましょう。

$ make html
$ cp -pr build/html/* ./
$ git add .
$ git commit -m 'add sphinx docment'
$ git push origin gh-pages

さて今度はどのように見えるでしょう。

f:id:tell-k:20120118193355p:plain

アレ? おかしいですね? スタイルシートが利いてないぽいですね。。

Jekyllを使わないようする

そもそも GitHub Pages は Jekyll という静的コンテンツを作成するためのシステムを利用しています。このJekyll は アンダースコアではじまる「_static」のようなディレクトリは旨く処理してくれないらしいです。

なので、それを回避するためにはルートディレクトリに「.nojekyll」というファイルを置けば、明示的にJekyllを利用しない形でコンテンツを配置できるっぽいです。

$ touch .nojekyll
$ git add .
$ git commit -m 'add .nojekyll'
$ git push origin gh-pages

これでどうなってでしょう?

f:id:tell-k:20120118194216p:plain

おぉ見れるようになりましたね! 長くなったんで今日はここまでにしましょう。まだこのままだと、ドキュメントを更新するために、いちいちmasterとgh-pages ブランチを切り替えないといけないですよね。次回は、その辺をgit submoduleを使って対応してみたいと思います。

余談

  • 「.nojekyll」の代わりにsphinxのプラグインである「sphinx to github」を使うという選択肢もあります。詳しくは参考をURLを参照してください。