GitHub Pages

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

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

空のGitHub Pagesブランチの作成

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

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

gh-pagesブランチの作成
1
2
3
4
> 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のページとして見れるようになります.

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

1
2
3
4
> 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化.
1
> git submodule add -f -b gh-pages github.com/[UserName]/[RepositoryName].git docs

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

gh-pagesブランチのsubmodule化.
1
2
3
4
5
6
7
8
9
10
11
12
13
# 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/