GitHub Pages

2015-08-01 GitHub

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

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

空のGitHub Pagesブランチの作成

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

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

  > 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と紐づけします．

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

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

  # 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/