2012年3月18日 19:22

GithubのリポジトリでJavaDocを公開する

先日Githubに自分用のライブラリを公開しました。
Githubに「gh-pages」というブランチを作ってpushすると静的なサイトを公開することができるため、それを応用してJavaDocも一緒に公開してみました。


gh-pagesをpushした場合「http://[ユーザー名].github.com/[リポジトリ名]/?」というURLで参照できます。

参考にしたサイト

以下の手順ではMavenで生成したJavaDocをコマンドベースでGithubにpushすることを想定しているのでそれ以外の場合は適宜読み替えてください

手順メモ
    1. [master] pom.xmlに下記を追加
      <project>
        <reporting>
          <outputDirectory>site</outputDirectory>
          <plugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
                <source>1.6</source>
                <encoding>UTF-8</encoding>
                <docencoding>UTF-8</docencoding>
                <charset>UTF-8</charset>
                <links>
                  <link>http://docs.oracle.com/javase/6/docs/api/</link>
                </links>
              </configuration>
            </plugin>
          </plugins>
        </reporting>
      </project>
      <outputDirectory>で出力先の設定。JavaDoc以外にもFindBugsやカバレッジのレポートもできるため詳しくはggrks(ググレカス)
    2. [master] .gitignoreに<outputDirectory>で追加した出力先を追加する
      echo site/ >> .gitignore
    3. [master] ここらでいったんコミット
      git add .
      git commit
      
    4. [master] 下記コマンドを実行
      git symbolic-ref HEAD refs/heads/gh-pages
      rm .git/index
      git clean -fdx
      よく分かってないですが、これをやることでどこのブランチからも切り離されたgh-pagesが作られるらしい
    5. [gh-pages] index.htmlを追加
      echo "My GitHub Page" > index.html
    6. [gh-pages] .gitignoreで適宜ファイルを除外したりする。
      (site/とindex.html以外は除外していいかと)
    7. [gh-pages]  ここらでいったんコミット
      git add .
      git commit
    8. [master] masterをcheckoutしてmvn siteする
    9. [gh-pages] gh-pagesをcheckoutしてsite/を追加
    10. [gh-pages] git push origin gh-pagesするとページが作られる。ファイル数にもよるけど多い時は10分くらいかかる

2回目以降はmasterでmvn siteする前にgh-pagesでrm -rf site/してコミットしておく(既存ファイルがあるとエラーになってcheckoutできないため)