github のプロジェクトにSphinxドキュメントを良さげな感じにおきたい 其の二
昨日の続き。色々なんか眠いので端折るでしかし。
面倒な事
昨日までの話だと、こんな感じに、ブランチを切り替えながら作業しなければなりません。
- Sphinxドキュメントを編集する -> gh-pagesブランチに切り替えて作業
- アプリを開発する -> masterブランチに切り替えて作業
これはめんどくさいですね。そこで「git submodule」を利用して、masterブランチ上に、gh-pagesのブランチをsubmoduleとして持ってしまいましょう。
これにより、ブランチを切り替えることなく、ドキュメントを編集する事が可能になります。
git submodule をつかう
git submoduleは、svnの外部リポジトリのような事ができます。実際に下記コマンドを入力してみましょう。
git submodule add -b gh-pages `git remote -v|grep fetch|awk '{print$2}'` docs
- `git remote -v|grep fetch|awk '{print$2}'` では github.comのcloneするときのURL?が取得できます。つまり今いるリポジトリですね。 ex) git@github.com:tell-k/sphinx-doctest.git
- gh-pages ブランチを、docsとういうディレクトリ名でsubmoduleとして登録します。
実行した後は、こんな感じに、READMEしかなかったmasterブランチに、docsディレクトリ、そしてgh-pagesのSphinxドキュメントのファイル群が確認できます。
. ├── README ├── .gitmodules └── docs ├── Makefile ├── _sources ├── _static ├── build ├── genindex.html ├── index.html ├── objects.inv ├── search.html ├── searchindex.js └── source
また「.gitmodules」というファイルが出来てると思います。この中身を除くと、submoduleの設定内容が確認できます。
[submodule "docs"] path = docs url = git@github.com:tell-k/sphinx-doctest.git
これで対応は完了です。ドキュメントを更新するときにbranchをいちいち切り替えずに作業を始められそうですね。
cloneした時のsubmoduleの初期化
他のマシン環境でも、このgithubのリポジトリを利用したいと思います。
普通に「git clone」で取得すると思いますが、最初は「submodule」の設定はなにもない状態だったります。
なのでcloneしたら、初期化してあげましょう。これで上記構成と同じ物が作られます。
git submodule init git submodule update
余談
- Sphinxドキュメントが前提なのであれば、最近はRead The Docsの方が主流になりつつあると聞いたので、そのへんのやり方も次回あたりまとめます。
追記(2012/01/20)
- Read The Docs を Read The Dog とかタイポしてたので修正。。。はずかし