万人のためのオートメーション: プッシュボタンによるドキュメント作成

開発者向けドキュメントおよびユーザー・マニュアルの作成を自動化する

ソフトウェア製品を提供する上で、プロジェクトのドキュメントの作成は必要悪の 1 つです。でも想像してみてください。ボタンのクリック 1 つでドキュメントを作成できたとしたらどうでしょう。連載「万人のためのオートメーション」では今回、オートメーションのエキスパート、Paul Duvall がオープンソースのツールを使って UML (Unified Modeling Language) 図、ビルド図、ERD (Entity-Relationship Diagram: エンティティー・リレーションシップ図)、さらにはユーザー・マニュアルの作成まで自動化する方法を紹介します。

Paul Duvall, CTO, Stelligent Incorporated

Paul DuvallPaul Duvall は、Stelligent Incorporated の最高技術責任者です。同社はアジャイル・コンサルタント会社として、開発チームが production-ready software を提供できるように支援しています。彼は Addison-Wesley Signature Series から出版されている『Continuous Integration: Improving Software Quality and Reducing Risk』(Addison-Wesley Professional、2007年、2008年度 Jolt Award を受賞) の共著者で、『UML 2 Toolkit』(Wiley、2003年) および『No Fluff Just Stuff Anthology』(Pragmatic Programmers、2007年) の著作にも貢献しました。



2008年 6月 10日

ソフトウェア開発プロジェクトのドキュメントを作成するのが好きだという開発者には、あまり出会ったことがありません。プロジェクトを放棄するつもりでない限り、そして (プロジェクトにとって良い兆しではないでしょうが) 常に開発を 1 人で行っていたり、ユーザーが 1 人もいなかったりするのでない限りは、ソフトウェアの目的を他の人々に伝えるための半永久的な手段が必要です。一部の開発者は、アジャイル・マニフェストの「包括的なドキュメントよりも動作するソフトウェアを重視する」という記述をドキュメントはまるで必要ないという意味に曲解しています (「参考文献」を参照)。その一方、ユーザーや他の開発者たちに不要なドキュメントを作成するという負担をかける必要もないので、私は普段その中間点を取っています。ご想像のとおり、この記事では自動化によってプロジェクトのドキュメント作成のプロセスを合理化する (そして苦痛を減らす) 方法を説明します。

この連載について

私たちは開発者として、エンド・ユーザーのプロセスを自動化するために作業しますが、自分自身の開発プロセスを自動化する機会は見落としがちです。そこで、連載記事「万人のためのオートメーション」では、実用的なソフトウェア開発プロセスの自動化を検討し、自動化を上手に適用するタイミングと方法を教えます。

私の経験では、2 つの重要な問題がソフトウェア開発でのドキュメント作成の妨げとなっています。その 1 つは、誰もドキュメントを読まないという可能性です。そしてもう 1 つのよくある問題は、ドキュメントの完成とほとんど時を同じくして、ドキュメントが古くなってしまうことです。この 2 つの問題の原因にはつながりがあります。ドキュメントが最新のものであったら、人々がドキュメントを読む可能性は高くなります。ドキュメントの作成を自動化すればドキュメントを最新のものに保てるようになり、それによってソフトウェアのユーザーにとって一層有益なドキュメントになるはずです。

以下に挙げた以外にも自動化の効果が期待できる類のドキュメント作成作業がありますが、ここでは私がよく苦労するドキュメント作成の作業を自動化する方法を重点に説明します (このリストに記載したツールへのリンクは「参考文献」を参照してください)。

  • 現行のソース・コードに基づく UML 図の生成。UMLGraph を使用
  • データベース内のテーブルとテーブル間の関係をドキュメントにするためのエンティティー・リレーションシップ図 (ERD) の作成。SchemaSpy を使用
  • Ant ビルド・ターゲットとこれらのターゲット間の関係を表すビルド図の生成。Grand を使用
  • ソース・コード・ドキュメントの生成。Doxygen を使用
  • ユーザー・マニュアルの作成。DocBook を使用

この記事では、以下のように連載のいつもの形で説明を進めていきます。

  1. それぞれの作業を手動で行う場合の問題を説明
  2. 話題としているドキュメント生成ツールまたは図を生成するツールと Apache Ant を併用した自動化の例を紹介
  3. サンプル・コードに基づくスクリプトで生成したドキュメントのイメージを記載

この連載の常として、記載する例で使用するのはすべて、無料で入手してプロジェクトで使用できるオープンソースのツールです。一部のツール (UMLGraph、Grand など) で付随して用いる GraphViz というツールは、それぞれのツールが生成する .dot ファイルを使用します。

コードから UML へのリバース・エンジニアリング

私がかつて取り組んだプロジェクトでは、今まで目にしたなかでもとりわけ素晴しく設計された UML 図が用意されていました。しかし、これはプロジェクトを開始する時点でのことでした。問題は、(ある特定のケースでの問題を挙げると) 技術リーダーがモデルを常に最新のソース・コードの状態に保てなかったこと、あるいは彼が貴重な時間を手動によるソースからモデルへのリバース・エンジニアリングに費やしていたことです。いずれにしても、最善のソリューションとは言えません。見事に作成された UML 図であっても、バージョン管理リポジトリーにチェックインされたコードが正確にモデルで表されていなかったら意味がないからです。こうした状況ではモデルを基に決定を下しても、実際のコードを基に下した決定でなければ、最終的に問題が発生することは目に見えています。

決定をする上で有意義で、しかも作成しやすい、最新状態の図にするには、図の生成をビルド・プロセスに組み込み、変更があるたびに (あるいは定期的に) 図を生成する継続的インテグレーション (CI) 環境を用意するという方法があります。

リスト 1 では、Ant、UMLGraph、Graphviz を使用してソース・コードからドキュメントを生成しています。

リスト 1. UMLGraph ドキュメント生成ツールを使用した Ant スクリプト
<property name="reports.dir" value="${basedir}/reports"/>
  <mkdir dir="${reports.dir}"/>
  <path id="project.path">
    <pathelement path="${basedir}/src"/>
    <pathelement path="${basedir}/lib"/>
  </path>
  <javadoc sourcepath="${basedir}/src" destdir="${reports.dir}" 
    classpathref="project.path" access="private">
    <doclet name="org.umlgraph.doclet.UmlGraphDoc" 
	  path="UMLGraph.jar">
        <param name="-attributes" />
        <param name="-enumerations" />
        <param name="-enumconstants" />
        <param name="-operations" />
        <param name="-qualify" />
        <param name="-types" />
        <param name="-visibility" />
    </doclet>
  </javadoc>
  <apply executable="dot" dest="${reports.dir}" parallel="false">
    <arg value="-Tpng"/>
    <arg value="-o"/>
     <targetfile/>
     <srcfile/>
     <fileset dir="${reports.dir}" includes="*.dot"/>
     <mapper type="glob" from="*.dot" to="*.png"/>
  </apply>

リスト 1 では、UMLGraph を Javadoc と組み合わせて Javadoc HTML レポート内に基本 UML クラス図を生成しています。各クラス図に表示される情報をカスタマイズするために、UmlGraphDoc を呼び出すときには以下の属性を渡します。

GraphViz によるグラフ化

UMLGraph が適切に機能するためには、Graphviz (「参考文献」を参照) をインストールして、Graphviz .dot ファイルがマシンのシステム・パスから使用できるようになっている必要があります。

  • -attributes はクラスのフィールドを表示します。
  • -enumerations は異なる列挙型を示します。
  • -enumconstants は列挙型に可能な値を示します。
  • -operations はクラスの Java メソッドを表示します。
  • -qualify は完全修飾クラス名を示します。
  • -types は引数のデータ型と戻り値の型を表示します。
  • -visibility はフィールドおよびメソッド修飾子 (publicprotectedprivate または default) を示します。

図 1 は、UMLGraph で HTML に生成した LoginDaoImpl クラスとその関係を表す UML 図の一例です。

図 1. UMLGraph で生成した UML 図

クリックして大きなイメージを見る

図 1. UMLGraph で生成した UML 図

UMLGraph ではこれよりもさらに複雑な関係と詳細情報が追加された UML 図を生成できますが、上記の単純な例に示した基本的な UML クラス図でさえも、かなりの情報を提供します。また、現行のコード・ベースを基礎としたソフトウェアを視覚的にわかりやすく表すという目的も果しています。このツールは、「本来、コードはこのようになるはずだった」といった類の発言をなくし、より適格な決定を行う可能性を与えてくれます (「参考文献」にリンクを記載した記事で、UMLGraph の出力をカスタマイズするのに使用できるさまざまな属性を説明しています)。


データベース・ドキュメントの作成

最新 UML 図の作成を自動化することが有益であるのと同じく、データベースの視覚表現を自動で作成できるようにすることにもメリットがあります。データベースの視覚化にもっともよく使われている図のタイプは、エンティティー・リレーションシップ図 (ERD) です。ERD を作成するツール (数あるなかの一例は ERWin です) のほとんどでは、ERD を手動で作成しなければなりません。そこで紹介するのが、SchemaSpy です。さらに高性能のツールも他にありますが、このツールは、データベースの全体的な ERD ビューを、制約、関係などと併せて作成することができます。その上、このツールを自動ビルドで実行すれば、バージョン管理リポジトリーでの DDL (Data Definition Language) の最新表現を難なくチェックすることができます。

リスト 2 の Ant スクリプトは、SchemaSpy ツールを使って Javadoc 用にフォーマット設定したファイルを作成します。

リスト 2. Ant および Javadoc での SchemaSpy の使用
<property name="reports.dir" value="${basedir}"/>
<java jar="schemaSpy_3.1.1.jar"
  output="${reports.dir}/output.log"
  error="${reports.dir}/error.log"
  fork="true">
  <arg line="-t mysql"/>
  <arg line="-host localhost"/>
  <arg line="-port 3306"/>
  <arg line="-db brewery"/>
  <arg line="-u root"/>
  <arg line="-p sa"/>
  <arg line="-cp mysql-connector-java-5.0.5-bin.jar"/>
  <arg line="-o ${reports.dir}"/>
</java>

リスト 2 では java Ant タスクによって SchemaSpy を呼び出し、以下の属性を渡しています。

  • -t はデータベースのタイプです (有効な値は mysqloradb2 など)。
  • -host はデータベースをホストしているマシンの名前です。
  • -port はデータベース URL のポート番号です。
  • -u はデータベースのユーザー名です。
  • -p はデータベースのパスワードです。
  • -cp はクラスパスです (データベース・ドライバーの JAR ファイルの場所を示すために使用します)。
  • -o は出力ディレクトリーの場所です。

SchemaSpy の上記のコマンドライン属性が、ERD を表示する HTML ファイルを生成するために使用されます (図 2 を参照)。

図 2. SchemaSpy および Ant で作成した ERD

ツールを組み合わせて使用し、データベースに対する ERD 生成スクリプトをビルドの一環として実行し、ERD 生成をスケジューリングすることで、開発中に素早く簡単にデータベースに関するさまざまな決定を行う手段が手に入ります。


ビルドの関係を表す図の作成

ビルド・スクリプトの依存ターゲット間に複雑な関係があることがよくあります。これまで私は、不要に重複して 1,000 行以上に膨れ上がったビルド・スクリプトを数多く目にしてきました。自動ビルドの全体図がない限り、このようなビルド・スクリプトは扱い切れません。ビルドが行うこと、あるいは行わないことを素早く判断するのに効果的な方法は、ビルドのターゲットとターゲット間の関係を図にすることです。Ant ターゲットの視覚モデルは効果的かつ目的に適った決定を行う際の助けとなり、ビルド・スクリプトの設計の改善につながります。

Ant、Grand、Graphviz を組み合わせると、ビルド・ターゲットの正確な視覚表現を作成することができます。Ant ターゲットを視覚化するツールは数多くありますが、Grand の利点は、Ant API を使用することです。そのため、Ant スクリプトが完全に機能しているかどうかに関わらず図を作成することができます。

リスト 3 の Ant スクリプトは、Grand ツールを使用して Ant スクリプトのターゲットをそのターゲット間の依存関係を含めた図で視覚的に表現する例です。

リスト 3. Ant および Grand を使用した Ant ターゲットを表す図の作成
<target name="create-ant-diagram">
  <property name="file.type"value="pdf" />
  <typedef resource="net/ggtools/grand/antlib.xml" 
    classpath="grand-1.8.jar"/>
  <grand output="build.dot"buildfile="${basedir}/build.xml"/>
    <execexecutable="dot" >
      <arg line="-T${file.type} -Gsize=11.69,8.27 -Grotate=90 -o build.${file.type} 
    ${grand.output.file}"/>
    </exec>
</target>

リスト 3 では、まず grand-1.8.jar を指定することによってタスクを作成します。次に、分析対象のビルド・ファイルの名前を buildfile 属性に指定します。output 属性は、ここで作成している Graphviz ファイル (build.dot という名前を指定) です。そして最後に dot 実行可能ファイルを呼び出して、buildfile に含まれるビルド・ターゲットの PDF を生成します。図 3 は、このファイルの一例です。

図 3. Ant、Grand、GraphViz で生成した Ant ターゲットを表す図

これらの図は、完成したプロジェクトの分析、あるいは開発中のプロジェクトのビルド・プロセスの改善に使用することができます。


コード・ドキュメントの作成

新しく作成した Java のクラスやメソッドの内容、場合によっては作成した理由を忘れないようにする場合、私は Java コードのコメントを書きますが、クラスやメソッド、そして属性の包括的なビューが必要な場合にはコード・ドキュメント生成ツールが必要になります。長年の間、Java プラットフォームではコード・ベースに含まれるすべてのクラスのコード・ドキュメントを生成する手段として Javadoc を提供してきました。実際、Ant では javadoc タスクが標準の手段としてコード・ドキュメントを生成します。しかし、開発者には一連の見苦しい HTML タグを Java ソース・コードのコメントに埋め込むという重荷が課せられます。リスト 4 は、Javadoc によるコード・コメントの一例です。

リスト 4. Javadoc の場合のコード・コメント
/**
  This is <i>the</i> LoginServiceImpl  class.  
  <p> 
  Refer to <a href="url.html">
  LoginService overview</a> for more details.
  <p>
  There is one type of supported {@link LoginServiceImpl }:
  <ul>
    <li>{@link LoginServiceImpl } (this class)</li>
  </ul>
*/

Doxygen を使用すれば、リスト 5 に示すように組み込み HTML が必要ないため、コード・コメントは遥かに簡潔になります。

リスト 5. Doxygen の場合のコード・コメント
/**
This is <i>the</i> LoginServiceImpl class.
Refer to \ref LoginService for more details.
There is one type of supported LoginService:
- LoginServiceImpl (this class)
*/

Javadoc と Doxygen はどちらもコード・ドキュメントの自動生成をサポートしていますが、Doxygen の場合はより直観的な方法でコメントを使ってソース・コードにアノテーションを付けられるため、容易にコード・ドキュメントの生成を自動化することができます。 リスト 6 の Ant スニペットに、最も基本的な Doxygen の使い方を示します。

リスト 6. Doxygen ドキュメント生成ツールを使用した Ant スクリプト
<target name="generate-doxygen">
  <taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask" 
    classpath="ant-doxygen.jar" />
  <doxygen configFilename="Doxyfile">
  <property name="INPUT" value="${src.dir}" />
  <property name="RECURSIVE" value="yes" />
  </doxygen>
</target>

リスト 6 の configFilename の値、Doxyfile は Doxygen で生成する構成ファイルの名前です。この値は、用途に合わせてカスタマイズすることができます。図 4 は、リスト 6 の Doxygen の例で生成した LoginDaoImpl クラスの HTML レポートの例です。

図 4. HTML Doxygen ドキュメント

クリックして大きなイメージを見る

図 4. HTML Doxygen ドキュメント

自動ビルドの一環として Doxygen ドキュメントを作成すれば、API の使用方法に関する最新の情報を入手することができます。


ユーザー・マニュアル

ここまでのところで、おそらく皆さんはテクニカル・ドキュメントを自動的に生成できるのはいいけれど、悩みの種はユーザー・マニュアルの作成にあると思っていることでしょう。ユーザー・マニュアルを作成していて私が思ったのは、マニュアル全体でテキストをコピー・アンド・ペーストするだけの作業にかなりの時間を費やしているということです。このプロセスの分析を始めてみたところ、バージョン番号やファイル名などの項目は、単一のソースに定義することで自動化できるはずだという確信を得ました。さらに、XML と XSL (Extensible Stylesheet Language) を使用してフォーマット設定とコンテンツとを切り離せば、スタイルシートを単純に変更するだけでマニュアルのルック・アンド・フィールを大々的に変更できるはずです。

登場してから長い年月になる DocBook は、XML でドキュメントを定義し、そのドキュメントを HTML や PDF をはじめとするさまざまなフォーマットで生成できるツールです。DocBook は、作成者が使用するテンプレートを定義するスキーマを提供します。

リスト 7 では、Ant、DocBook XSL ファイル、XSL-FO (XSL Formatting Objects) の組み合わせを使って私のユーザー・マニュアル (「参考文献」を参照) の PDF を生成しています。

リスト 7. Ant、DocBook、FO による PDF の作成
<target name="pdf" depends="init" description="Generates PDF files from DocBook XML">
  <property name="fo.stylesheet" value="${docbook.xsl.dir}/fo/docbook.xsl" />
  <xslt style="${fo.stylesheet}" extension=".fo" basedir="${src.dir}" destdir="${fo.dir}">
    <classpath refid="xalan.classpath" />
    <include name="${guide}.xml" />
  </xslt>
  <property name="fop.home" value="lib/fop-0.94" />
  <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">
    <classpath>
      <fileset dir="${fop.home}/lib">
        <include name="*.jar" />
      </fileset>
      <fileset dir="${fop.home}/build">
        <include name="fop.jar" />
        <include name="fop-hyph.jar" />
      </fileset>
    </classpath>
  </taskdef>
  <fop format="application/pdf" fofile="${fo.dir}/${guide}.fo" 
    outfile="${doc.dir}/${guide}.pdf" />
</target>

図 5 は、リスト 7 のスクリプトによって生成された PDF からの抜粋です。

図 5. ユーザー・ガイド・マニュアルの PDF

コンテンツはすべてテキスト・ベースの XML で定義されているため、マニュアル全体を変更するスクリプトは簡単に作成することができます。さらに、これらのマニュアルをビルド・プロセスの一部として生成すれば、唯一の標準ソースでバージョン、定義、略語、ファイル名、ディレクトリーなどの要素を定義できるようになります。


ドキュメントの作成を手動で行う必要はありません

この記事を読んで、ドキュメントの作成を自動化する効果的な方法があると納得していただけたことを願っています。私の考えでは、ドキュメント作成の最も重要な側面は意思の疎通であり、ドキュメントを生成するプロセスではありません。ここで説明した自動化のツールや手法は、ドキュメントを正確かつ最新の状態に保つことによって、ドキュメントが十分に活用されないという常習的な問題の原因、つまり古くなった情報を排除するという効果があります。

参考文献

学ぶために

製品や技術を入手するために

  • Ant: Ant をダウンロードして、分かりやすく繰り返し可能な形でソフトウェアのビルドを開始してください。
  • Grand: Ant ビルド・プロセスを図にする Grand をダウンロードしてください。
  • SchemaSpy: データベースの ERD を作成する SchemaSpy をダウンロードしてください。
  • Doxygen: 詳細なドキュメントを生成できる Doxygen をダウンロードしてください。
  • UMLGraph: ソース・コードから UML 図へのリバース・エンジニアリングを自動で行う UMLGraph をダウンロードしてください。
  • DocBook: コンテンツをさまざまなフォーマットで生成する DocBook をダウンロードしてください。

議論するために

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Java technology, Open source
ArticleID=318737
ArticleTitle=万人のためのオートメーション: プッシュボタンによるドキュメント作成
publish-date=06102008