[ English | Japanese ] [ 地球流体電脳倶楽部 / gtool プロジェクト ] [ gtool5 ドキュメント ]

gtool5 ドキュメントの概説と保守管理の解説

本文書は gtool5 ライブラリのドキュメントを概観し、 その保守管理について記します。


  1. 概説
  2. 保守管理に必要なソフトウェア
  3. rdtool を用いたドキュメントの保守管理
  4. RDoc を用いたドキュメントの保守管理
  5. ChangeLog の保守管理
  6. 一括でのドキュメント生成

概説

gtool5 では以下の種類のドキュメントを用意しています。

これらの文書は HTML (または XHTML) となっており、 ブラウザから参照することが想定されています。

しかし、保守管理を容易にするため、それぞれの文書は HTML を直接編集するのでは無く、 別途ソースとなるファイルを用意し、そのファイルから HTML を自動生成するようにしています。 上記文書のうち、末尾に [rdtool] と記述されているものは、 RD (Ruby Document) 形式のテキストをソースファイルとしており、 [RDoc] と記述されているものは、Fortran 90/95 コードをソースファイルとしています。 [cvs2cl] と記述されているものは、CVS で管理されているバージョン情報やログ情報をソースとしています (例外的に「ソースファイル」という形態では管理していません)。

以下ではその保守管理のために必要なソフトウェア、 HTML 生成のための具体的な手順について記します。

保守管理に必要なソフトウェア

上記ドキュメントを保守管理する際には、 以下のソフトウェアが必要となります。

以降では、これらを以下のように実行できることを想定して解説します。 システムへのインストールやパスの設定を適切に行ってください。

rdtool を用いたドキュメントの保守管理

コードリファレンスや ChangeLog などの一部の文書を除き、 ドキュメントのほとんどは、 RD 形式のテキストファイル (以降は RD ファイルと呼びます) として管理され、これを rdtool を用いて HTML に変換して公開されます。

以下では、それぞれ

  1. RD ファイルの編集
  2. 新規のディレクトリの作成と RD ファイル管理に必要な作業

を行うための手順を記します。

また、例外として doc 以下に置いていない RD 形式のドキュメントの管理 についても記します。

RD ファイルの編集

一連の手順は以下のようになります。

  1. RD 形式のテキストファイルの作成もしくは編集
  2. rdtool と GNU Make による HTML の作成

以下では、この 2 つの手順の詳細を記します。

1. RD 形式のテキストファイルの作成もしくは編集

RD 形式のテキストファイルの書き方については、 地球流体電脳倶楽部 dcmodel プロジェクト: モデルプロジェクトのための最低限 rd -- rd ファイルの作成 を参考にしてください。

ファイルを新規作成した場合には、そのファイルの拡張子を rd とし、 doc ディレクトリに置いてください。

2. rdtool と GNU Make による HTML の作成

HTML を作成する際には、doc ディレクトリ以下で 以下のように make を実行してください。

$ make rd2html

これにより、拡張子 rd のファイルから、その拡張子を htm および htm.en に置き換えたファイルが作成されます。

|****.rd  =====[make]=====>  ****.htm, ****.htm.en 

直接 rd2 コマンドを入力する必要はありません。 事前に用意されている Makefile および Makefile.rd2html 内で rd2 コマンドが実行されるとともに、その他のいくつかの処理が行われます。

新規のディレクトリの作成と RD ファイル管理に必要な作業

RD ファイルの編集 において、 rdtool を用いたドキュメントの日常的な保守管理方法を記しました。

以下では、doc 以下に新たなディレクトリを作成してそこにドキュメントを作成する場合について記します。 ここでは、doc 以下に users というディレクトリを作成し、 そこでドキュメントを管理することを想定して解説します。

1. Makefile.rd2html のダウンロード

users ディレクトリを作成し、そこに移動した後、 地球流体電脳倶楽部 dcmodel プロジェクト: モデルプロジェクトのための最低限 rd より Makefile.rd2html をダウンロードします。

$ mkdir users
$ cd users
$ wget http://www.gfd-dennou.org/library/dcmodel/doc/sample_Makefile/Makefile.rd2html

2. Makefile の作成

users ディレクトリ以下に Makefile を作成します。 サンプル Makefile をダウンロードし、Makefile にリネームしてください。

$ mv lib-overview-doc.Makefile Makefile

Makefile について、以下の項目について編集を行ってください。 編集が必須となる項目は "< >" で括られています。

3. 動作テスト

以上でとりあえずの準備は完了です。 RD ファイルを users ディレクトリに置いた後、 HTML ファイルの作成と削除を試してください。

4. Makefile.rd2html の編集

ダウンロードした Makefile.rd2html の冒頭には、 HTML 生成に関する各種設定項目が並んでいます。 スタイルシートファイルやヘッダ、フッタなど、 必要に応じて適宜修正を行ってください。

既に作成されている doc や doc/tutorial 以下の Makefile.rd2html を参考にして下さい。

5. doc ディレクトリの Makefile の編集

トップディレクトリで make doc や make install-doc コマンドを入力した際に、 doc/users 以下でも HTML の生成もしくはインストールが為されるよう、 doc 直下の Makefile の編集を行います。 以下のように SUBDIRS 変数に、作成したディレクトリを追記してください。

SUBDIRS=images tutorial users

doc 以下に置いていない RD 形式のドキュメントの管理

例外的に、doc 以下に置いていない文書として、 インストールガイド開発履歴使用上の注意とライセンス規程 といったものがあります。

これらのソースファイルには拡張子 rd を付加せず、 それぞれ INSTALLHISTORYCREDITS がソースファイルとなっています。

これらから htm, htm.en ファイルを作成する際には、 gtool5 トップディレクトリにおいて以下のコマンドを入力します。

$ make guide

RDoc を用いたドキュメントの保守管理

コードリファレンスは、 RDoc Fortran90/95 ソースコード解析機能強化版 を用いて、Fortran 90/95 ソースコードから自動生成されています。 以下では、

  1. RDoc を用いたドキュメントの日常的な保守管理
  2. RDoc によるドキュメント生成の設定変更

について記します。

RDoc を用いたドキュメントの日常的な保守管理

一連の手順は以下のようになります。

  1. Fortran ソースコードの編集
  2. RDoc と GNU Make による HTML の作成

以下では、この 2 つの手順の詳細を記します。

1. Fortran ソースコードの編集

Fortran ソースコード中に既定の書法でコメントを記述することで、 これをコードリファレンスに反映することが可能です。 書法については、 チュートリアル: RDoc による数値モデルの自動ドキュメント生成7.2 RDoc によるドキュメント生成 -- コメントを書き込んでみる および 8.1 RDoc の便利な機能を使ってみる -- コメント部の修飾 を参考にして下さい。 詳細については RDoc Fortran 90/95 解析機能強化版におけるコメントの書き方 を参照してください。

2. RDoc と GNU Make による HTML の作成

doc ディレクトリ以下で以下のコマンドを入力することで、 Makefile が rdoc コマンドを呼び出し、コードリファレンスが生成されます。

$ make rdoc rdoc-dev

直接 rdoc コマンドを入力する必要はありません。 事前に用意されている Makefile、Makefile.rdoc、Makefile.rdoc-dev 内で rdoc が実行されるとともに、その他のいくつかの処理が行われます。

RDoc によるドキュメント生成の設定変更

RDoc を用いたドキュメントの日常的な保守管理 において、 RDoc を用いたドキュメントの日常的な保守管理方法を記しました。

以下では、RDoc におけるドキュメント生成の際の設定の変更について記します。

RDoc 生成用 Makefile の設定項目

doc ディレクトリ以下の Makefile.rdocMakefile.rdoc-dev が、 それぞれ利用者用、開発者用コードリファレンス作成の Makefile です。 以下では利用者用コードリファレンス作成用 Makefile をサンプルに、 設定項目を挙げます。

ChangeLog の保守管理

ChangeLog は、CVS で管理されているバージョン情報やログ情報をソースとしています。 更新のためには、CVS リポジトリへアクセスする必要があります。

更新は gtool5 トップディレクトリで以下のコマンドを入力します。

$ make cl

これにより、ChangeLog が更新されます。

一括でのドキュメント生成

rdtool や RDoc を用いたドキュメントについて、 その生成を一括で行うには、gtool5 トップディレクトリで

$ make doc

とするか、doc ディレクトリ以下で

$ make

として下さい。

ただし、ChangeLog のみ別途生成する必要があります。


$Id: lib-overview-doc.rd,v 1.5 2009-03-31 12:46:30 morikawa Exp $
gtool Development Group / GFD Dennou Staff dcstaff@gfd-dennou.org