8月 1 2015

GitHub Pages

GitHub Pagesのど導入に関してのメモ

まだあまりGitHubの操作に慣れていないせいもあり，少し戸惑う部分もありました．
公式ページのCreating Project Pages manuallyが参考になります．

空のGitHub Pagesブランチの作成

まず，プロジェクトサイトから，gh-pagesブランチをorphan(履歴が無いクリーンなブランチ)オプション付きで作成します．

具体的には，以下のコマンドで作成します．

gh-pagesブランチの作成

> git clone github.com/[UserName]/[RepositoryName].git
> cd [RepositoryName]
> git checkout --orphan gh-pages
> git rm -rf .

普段使っているリポジトリをcloneし，gh-pagesブランチに切り替え，中身と履歴を消去しています．

ページコンテンツの作成

新しく作成されたgh-pagesブランチ内に，index.htmlを配置すれば，GitHub Pagesのページとして見れるようになります．

公式ヘルプからの抜粋ですが，例えば，以下のようなコマンドで初期ページを作成できます．

> echo "My Page" > index.html
> git add index.html
> git commit -a -m "First pages commit"
> git push origin gh-pages

作成したページのURLは，https://[UserName].github.io/[RepositoryName]になります．

Doxygenで生成したドキュメントの配置

元々のGitHub Pagesの使い方からはずれているかもしれませんが，Doxygenで生成したmasterブランチのAPIドキュメントをsubmoduleを使ってGithub Pagesで公開する手法をまとめます．

Doxygenでは，自作したコードのコメントを元にAPIドキュメントを生成することが出来ます．
例えば，

• [RepositoryName]
  • docs
  • src

の構成で，docsにAPIドキュメントを配置することにします．

ここでsubmoduleを使って，docsに出力された内容をGitHub Pagesに間接的に公開することが出来ます．

まず，先ほど作成したgh-pagesのブランチをsubmodule化し，masterブランチのdocsと紐づけします．

gh-pagesブランチのsubmodule化．

> git submodule add -f -b gh-pages github.com/[UserName]/[RepositoryName].git docs

後は，doxygenで生成したAPIドキュメントに対し，変更内容をgh-pages，masterの両方で更新すればGitHub PagesでAPIドキュメントを見られます．

gh-pagesブランチのsubmodule化．

# APIドキュメントの生成
> doxygen Doxyfile

# gh-pagesブランチの更新
> cd docs
> git add .
> git commit -m 'Update docs(gh-pages)'
> git push origin gh-pages

# masterブランチの更新
> cd ..
> git add docs/
> git commit -m 'Update docs(master)'

doxygen側の設定で工夫すれば，submodule化は特に必要ないかもしれませんが，submoduleの使い方の勉強にはなったかと思います．

参考文献

[1]　GitHub Pages: https://pages.github.com/
[2]　GitHub Pages Help (Creating Project Pages manually): https://help.github.com/articles/creating-project-pages-manually/
[3]　Doxygen: http://www.doxygen.jp/

GitHub

GitHub