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 とかタイポしてたので修正。。。はずかし