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にアクセスすると、ご丁寧にページの作り方が書いてあります。
この通りにやってみましょう。
$ 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" が見れると思います。やったね。
もとの 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
さて今度はどのように見えるでしょう。
アレ? おかしいですね? スタイルシートが利いてないぽいですね。。
Jekyllを使わないようする
そもそも GitHub Pages は Jekyll という静的コンテンツを作成するためのシステムを利用しています。このJekyll は アンダースコアではじまる「_static」のようなディレクトリは旨く処理してくれないらしいです。
なので、それを回避するためにはルートディレクトリに「.nojekyll」というファイルを置けば、明示的にJekyllを利用しない形でコンテンツを配置できるっぽいです。
$ touch .nojekyll $ git add . $ git commit -m 'add .nojekyll' $ git push origin gh-pages
これでどうなってでしょう?
おぉ見れるようになりましたね! 長くなったんで今日はここまでにしましょう。まだこのままだと、ドキュメントを更新するために、いちいちmasterとgh-pages ブランチを切り替えないといけないですよね。次回は、その辺をgit submoduleを使って対応してみたいと思います。
余談
- 「.nojekyll」の代わりにsphinxのプラグインである「sphinx to github」を使うという選択肢もあります。詳しくは参考をURLを参照してください。