めいふの備忘ログ

やったことを忘れないように書きこのしておくのです。

StrategyパターンでNGramモデルの文生成器を作った時のおもいで（プログラム作成の一般的方法論 ドキュメンテーション/リリース の段）

2.4 仕様書の作成（ドキュメンテーション）

前回までの内容でNGramモデルのプログラムの設計と実装も終わり、Unit Testも通りました。ここからはプログラムの公開のために行った作業についての備忘ログを書いていきたいと思います。

自分が作ったプログラムを他の人に公開する際には、プログラムのドキュメントも合わせて公開します。ドキュメントには、クラスについてはその責務を、メソッドの引数、返り値などについて説明されているとよいでしょう。

ラピッドプロトタイピング時や研究用のプログラムなどは、作るのが精一杯で、ドキュメンテーションの必要性を感じないこともあるのですが、ドキュメントは忘れた時の備忘ログにもなりますし、後輩に研究を引き継ぎぐときにも役立つなど、色々とうれしいことがあります。ドキュメンテーションは優しさなのです。

eclipseでJavaプログラムを書いた場合には、Javadocでドキュメンテーションを行うのが楽です。JavaDocとドキュメンテーションの心得についてはこちらが勉強になりました。ありがとうございました。

qiita.com

Javadocの書き方については以下のサイトが参考になりました。ありがとうございました。

www.javadrive.jp

こちらのサイトも参考にいたしました。ありがとうございました。

promamo.com

eclipseのFile＞ExportでJavadocを選択すればソースコードのコメントを元にJavadocが生成されます。せっかく公開するのならドキュメンテーションは英語で行ったほうが良いのです。英語ですと世界中の人たちの眼にとまることになります。ですが、今回は日本語で記述しています。太宰治の走れメロスは日本語ですし、形態素解析はkuromojiの日本語解析なので、まあ、今回は、妥協したのです…。

なお、（後段の節で手順を書いていますが）今回のNGramのプログラムはgithubのほうにもアップしていて、そのdoc下にJavadocが格納されています。

https://github.com/meihuno/sentencegenerator

2.5 リリース（インテグレーション）

自分のプログラムが完成したらgitやsvnにcommitして他の人たちにソースコードを公開します。

複数のプログラムやモジュールで構成されるシステムやプロダクトの開発ですと、ここからそれらのプログラムやモジュール群を結合して、システムとして複数のモジュールが正しく協調動作しているかのチェックを行います。これを結合テストといいます。しかし、今回は言語処理の教科書の演習問題のプログラムなので、何かのシステムの一部というわけではないのです。

今回はNGramプログラムを以下の手順で公開したのでその手順を公開しておくことにします。

・githubのmavenリポジトリの設定（pom.xml）
・githubに maven プロジェクトをdeploy
・maven プロジェクトの他のプロジェクトへの取り込みテスト

2.5.1 githubでの maven リポジトリの設定（pom.xml）

NGramのプログラムは最初からeclipseのmavenプロジェクトとして作成していきました。このソースコードはgithubにcommitして、maven プロジェクトのリリース物をgithub上のmaven リポジトリに deloyしていきたいと思います。

まずは、pom.xmlに githubのmavenリポジトリの設定を行います「github maven」あたりで検索して検索結果に含まれたブログで参考にしたのは以下です。ありがとうございました。

m12i.hatenablog.com

注意点として、githubのユーザプロファイル周りの注意点はここを参考にしました。ありがとうございます。

yo1000.hateblo.jp

また、ワタクシの環境では、maven の setting.xmlには githubへのaccess tokenを設定しなければうまく設定できませんでした。その情報についてはこちらのサイトを参考にさせていただきました。

qiita.com

結局、ワタクシめの pom.xmlのmaven リポジトリの関連の設定は以下のようになっています（抜粋）。

<groupId>nlp.sample</groupId>
<artifactId>sentencegenerator</artifactId>
<version>0.0.3</version>
<packaging>jar</packaging>

<name>sentencegenerator</name>
<!-- github の リポジトリ の url をセット -->
<url>https://github.com/meihuno/sentencegenerator</url>
  
<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <!-- maven の setting.xmlにおける github関連要素名 をセット -->
  <github.global.server>github</github.global.server>  
</properties>

<!-- maven リポジトリ用の githubのブランチについて -->
<distributionManagement>
   <repository>
    <id>internal.repos</id>
    <name>Temporary Staging Repository</name>
    <url>file://${project.build.directory}/mvn-repo</url>
   </repository>
</distributionManagement>

<build>
  <plugins>
    <!-- JUnitなど他のplugin設定については省略しています -->

    <!-- maven delopy 用の設定 -->
  <plugin>
    <artifactId>maven-deploy-plugin</artifactId>
     <version>2.8.1</version>
      <configuration>
       <altDeploymentRepository>internal.repo::default::file://${project.build.directory}/mvn-repo</altDeploymentRepository>
      </configuration>
  </plugin>

   <!-- github用の設定 -->
   <plugin>
     <groupId>com.github.github</groupId>
     <artifactId>site-maven-plugin</artifactId>
     <version>0.12</version>
     <configuration>
      <!--  <merge>true</merge> -->
                
      <!-- Git コミットメッセージ -->
      <message>Maven artifacts for ${project.version}</message>
      <noJekyll>true</noJekyll>
      
      <server>github</server>
           
      <!-- distributionManagement の url と一致させる -->
      <outputDirectory>${project.build.directory}/mvn-repo</outputDirectory>
           
        <!-- リモートブランチ名 -->
       <branch>refs/heads/mvn-repo2</branch>
       
       <includes><include>**/*</include></includes>
           
       <repositoryName>sentencegenerator</repositoryName>
       
       <!-- Github リポジトリユーザー名 -->
       <repositoryOwner>meihuno</repositoryOwner>
           
     </configuration>
     <executions>
      <execution>
        <goals>
          <goal>site</goal>
        </goals>
       <phase>deploy</phase>
      </execution>
    </executions>
   </plugin>
 </plugins>
</build>

2.5.2 githubに maven プロジェクトをdeploy

まず NGgramのプログラムのソースコードをgithubにcommitします。

$ git init
$ git add .
$ git commit -m "modified pom.xml for adjusting repository url"
$ git remote add origin https://github.com/meihuno/sentencegenerator.git
$ git push -u origin master

なお、.gitignore に /target/を追加してjarファイルをcommitしないようにしたりしています。そして、remoteリポジトリに対してmaven deployします。この辺は参考にしたサイトさんの手順そのまんまです。

$ maven clean deploy

deployされたgithub上のmavenリポジトリはこちらです。リポジトリの名前がmvn-repo2というあたりに色々苦労の後が伺えてしまうのです。

GitHub - meihuno/sentencegenerator at mvn-repo2

maven で buildすると eclipse の JUnit4が通らなくなるのでmaven clean を行ってmaven の buildをリセットしたりと、色々とmaven様には苦労させられました。githubへもaccesstokenがないとうまくアクセスできたりできなかったり。maven！いいかげんにせんか！とシャウトすることもあったのです…。この辺は慣れなのでしょうか。

さて、最後に「maven プロジェクトの他のプロジェクトへの取り込みテスト」については新しい記事でログを残しておきたいと思います。反省会もそちらでいたします…