TmDoc - Rubyソフトウェアの保守ドキュメントを作成

[ ENGLISH | JAPANESE ] [ Link to: RAA Entry ]

Wellcome to TmDoc project's home page!!

目次
概要
ダウンロード
必要条件
ライセンス
インストール
使い方
出力例
TmDocハッキングに関する補足

概要

TmDocはRubyソフトウェア向けの保守ドキュメント作成ツールであり、 ソースコードからDocBook文書を自動的に生成します。

ダウンロード

バージョン 日付 ファイル リリースノート
0.0.4 2012-04-20 tmdoc-0.0.4.tar.gz
  • 各Sourcesページ内で行番号付きの情報ボックスを追加
0.0.3 2011-12-22 tmdoc-0.0.3.tar.gz
  • モジュール/クラス宣言および include/extend 指示に関する "::" 演算子をサポート
    • 出力例 にある RubyTk と Radiant の文書を参照
    • 定数を伴う "::" 演算子は、まだサポートされていません
  • module_function 指示をサポート
0.0.2 2011-11-09 tmdoc-0.0.2.tar.gz
  • モジュール、クラス、そしてプロパティに関する キーワードの索引化をサポート
  • 新規追加オプション: --quiet, --sort-by-name
0.0.1 2011-10-16 tmdoc-0.0.1.tar.gz
  • 最初のリリース

必要条件

ライセンス

Ruby's ライセンス

インストール

標準の setup.rb 手続きです。 

  $ tar xfz tmdoc-X.X.X.tar.gz
  $ cd tmdoc-X.X.X
  $
  $ ruby setup.rb config
  $ ruby setup.rb setup
  $ sudo ruby setup.rb install

使い方

以下の手順は、UNIX環境における最も基本的なTmDocの使用方法です。

(1) 出力先ディレクトリを作成 
$ mkdir dbook
(2) コマンド tmdoc を実行 
$ tmdoc foo.rb
(3) 作成されたDocBookファイルをHTML形式へ変換 
  $ xsltproc --xinclude $DOCBOOK_XSL_DIR/html/docbook.xsl dbook/tmdoc.home.docbook > foo.html

出力例

共通ファイル: README.txt, Makefile, Make.Common, Make.Rules, dbook-to-html.xsl, tmdoc.css

名前 説明 ダウンロード 関連ファイル TmDoc オプション ログファイル
Net Network client library (Ruby 1.8.7 標準ライブラリ) EPUB Makefile
__dummy__.rb 		- LOG.txt
REXML XML parser library (Ruby 1.8.7 標準ライブラリ) EPUB Makefile
__dummy__.rb 		--tab-width 2 LOG.txt
RubyTk GUI toolkit (Ruby 1.8.7 標準ライブラリ) - Makefile
__dummy__.rb 		--show-class-siblings LOG.txt
WEBrick Web server toolkit (Ruby 1.8.7 標準ライブラリ) EPUB Makefile --show-all LOG.txt
databasedotcom 1.3.0 A ruby wrapper for the Force.com REST API EPUB Makefile --show-all LOG.txt
ActiveSupport 2.3.14 Utility classes and Ruby extensions from Rails - Makefile
__dummy__.rb 		- LOG.txt
The Depot Online Store This application implements an online store, with a catalog, cart, and orders. EPUB Makefile
__dummy__.rb 		--show-all LOG.txt
Radiant 1.0.1 Content Management System - Makefile
__dummy__.rb 		--show-module-siblings LOG.txt
Redmine 1.4.0 Flexible project management Web application - Makefile
__dummy__.rb 		- LOG.txt
TmDoc 0.0.4 Maintenance document producer for Ruby software - Makefile
Make.FILES 		--show-all
--tab-width 4 		LOG.txt

EPUB版の各文書は BOOKSHOP(bookshop-0.0.4) を使ってDocBook形式から変換しました。
[注意] BOOKSHOPの最新版(bookshop-0.0.18)では、 DocBookのサポートが打ち切られたらしい .... orz

TmDocハッキングに関する補足

ソフトウェア アーキテクチャ

TmDocシステムは 「階層化パイプラインアーキテクチャ(Layered Pipeline Architectire)」を元に 設計されています。

システムにおける中核の構成要素が 「モデル(Module: Model (TmDoc))」と 「トランスフォーマ(Module: Transformer (TmDoc))」です。 モデルは LSM(Logical Space Model, 論理空間モデル)宣言で強く型付けされた 不変オブジェクト(immutable object)であり、 トランスフォーマは あるモデルオブジェクトをもう一つのモデルオブジェクトへ変換する関数です。

用語「階層化パイプラインアーキテクチャ」は、 「階層化アーキテクチャ」と「パイプラインアーキテクチャ」とを組み合わせた合成語です。 以下の書籍では、これらアーキテクチャの利点と欠点を詳細に考察しています。

「ソフトウェアアーキテクチャ - ソフトウェア開発のためのパターン体系」,
F. ブッシュマン/H. ローネルト/M. スタル/R. ムニエ/P. ゾンメルラード, 株式会社トッパン, 1999年, ISBN4-8101-9007-2

LSM - 論理空間モデル

LSM(Logical Space Model, 論理空間モデル, Module: Lsm (TmStd)) は、以下の古い文献で紹介されている抽象データ型のRuby実装です。

「標準構造に基づく系統的ソフトウェア設計法 (<小特集>プログラム設計技法)」,
片岡雅憲/金藤栄孝/宮本和靖/山野紘一, 情報処理 Vol.25 No.11 (Nov. 1984)

字句解析と構文解析

Rubyコードの字句解析処理(Class: Scanner (TmDoc::Reader::Ruby18))と構文解析処理(Module: Parser (TmDoc::Reader::Ruby18))は、 Dave Thomas氏によって書かれたRuby標準ライブラリであり、 事実上のRuby標準ドキュメンテーションシステムでもある RDoc のコードを改造母体にしています。

RDocの構文解析コードの原型は、 石塚圭樹氏によって書かれました(RDoc添付のREADMEから引用)。 この原型コードは、 一般に「再帰下降構文解析」と呼ばれる古典的な手法を元にしています。 以下の書籍では、作者本人の手によって原型コードが解説されています。

「オブジェクト指向スクリプト言語Ruby (ASCII SOFTWARE SCIENCE Language)」,
まつもとゆきひろ/石塚圭樹, 株式会社アスキー, 1999年, ISBN4-7561-3254-5

[ HOME ]