Author: | Geoffrey Biggs and contributors |
---|---|
Date: | 2010-10-24 |
Copyright: | EPL-1.0 |
Version: | 3.0 |
Manual section: | 1 |
Manual group: | User commands |
rtdoc [options] <path>
RTコンポーネントのドキュメンテーションを表示します。
あるRTコンポーネントは内部的にドキュメントを含んでおり、それは、隠され たコンフィグレーションセットに保存されています。 このツールでそのドキュメンテーションを複数のフォーマットで表示できます。 対応フォーマットは reStructuredText、HTML、およびPDFへのコンパイルに 適しているLaTeXです。
-f FORMAT, --format=FORMAT | |
フォーマットを選択します。 rst 、 html および latex から選択し てください。 | |
-g, --graph | コンポーネントのグラフを表示させます。 |
--version | プログラムのバージョン番号を表示して終了する |
-h, --help | ヘルプを表示して終了する |
-v, --verbose | 冗長な情報を出力する [デフォルト: False] |
このツールに対応するためにRTコンポーネントは __doc__ というセットに ドキュメンテーションを保存しないとなりません。このセットでの隠されていな いパラメータはすべてセクションとしてドキュメンテーションに追加されます。 隠されたセットは名が __ で囲まれています。
一般のセクションは以下の通りです:
intro コンポーネントの紹介です。目的を短く説明します。(Title: ``Introduction``.) reqs ほかの必要なソフトなどのコンポーネントを使うための要件です。 (Title: ``Pre-requisites``.) install コンポーネントのインストール手続きです。 (Title: ``Installation``.) usage コンポーネントの使い方です。(Title: ``Usage``.) misc ほかの必要な情報です。(Title: ``Miscellaneous``.) changelog コンポーネントのバージョン間の変更を説明します。 (Title: ``Changelog``.)
上記に加え、コンポーネントにポートがある場合、 ports というセクションが 自動的に作られて、 default というセットにコンフィグレーションパラメー タがある場合、 config というセクションが自動的に作られます。 __doc__ セットにほかのセクションがある場合、それも自動的に作られます。
拡張情報をドキュメンテーション前文に追加するため、3つパラメータをセッ トすることもできます。 __doc__ セットにパラメータを設定してください。
- __license__
- コンポーネントのライセンス。LGPL、BSD等。
- __contact__
- 開発者の連絡先。メールアドレス等。
- __url__
- コンポーネントのウェブサイト。
ドキュメンテーションのパラメータはソースまたはコンフィグレーションファイ ルに設定することも可能です。ソースに設定した場合コンポーネントを使う時に必 要なメモリーが大きくなることがあるので、ファイルの方がおすすめです。
ソースに設定する場合は以下のようにできます:
'conf.__doc__.__license__', 'LGPL', 'conf.__doc__.__contact__', 'a@example.com', 'conf.__doc__.__url__', 'http://www.openrtm.org', 'conf.__doc__.intro', 'This is the introduction.', 'conf.__doc__.reqs', 'This component requires nothing.', 'conf.__doc__.install', 'Type "make install"', 'conf.__doc__.usage', 'Run comp_standalone.', 'conf.__doc__.misc', 'Extra information.', 'conf.__doc__.changelog', 'No changes.', 'conf.__doc__.Another', 'A non-standard section.',
デフォルトでセクションは以下の順番に表示します。
intro, reqs, usage, ports, config, misc, changelog, [他のセクション]
__doc__ セットの __order__ というパラメータを設定することによって 変更することが可能です。パラメータ名のリストにコンマ区切りで設定してください。 パラメータ名はセクションを示します:
'conf.__doc__.__order__', 'intro,ports,config,reqs,Another'
このパラメータに入っていないセクションはその後に表示します。
ポートのドキュメンテーションは description というプロパティをポートに 追加します:
self._inport.addProperty('description', 'This port receives stuff.')
コンフィグレーションパラメータのドキュメンテーションは __description__ というセットに設定します:
'conf.default.param', '0', 'conf.__description__.param', 'A test parameter.',
rtshell は パス でRTCツリーのオブジェクトを示します。パスは オブジェクトのアドレスです。ネームサーバとネームコンテクストは ダイレクトリで、マネージャとRTコンポーネントはファイルです。POSIXの cat 等のコマンドと同じように、コマンドに渡したパスはrtshellの ワーキングディレクトリに追加されます。rtshellの現在のワーキングディレクトリは RTCSH_CWD という環境変数に保存されて、 rtcwd というコマンドで 変更することができます。
利用できるパスはコマンド実行時のネームサーバによって変わります。 RTCSH_NAMESERVERS という環境変数の値に記録されたネームサーバとパスに 指定された ネームサーバを組み合わせて提供します。
例えば、 /localhost/comp0.rtc は localhost にあるネームサーバに登録 された comp0.rtc というRTコンポーネントを示します。 /localhost/manager/comp0.rtc は localhost にあるネームサーバの下の manager というディレクトリに登録された comp0.rtc というRT コンポーネントを示します。 ./comp0.rtc は現在のワーキングディレクトリ の中にある comp0.rtc というRTコンポーネントを示します。
RTコンポーネントのポートを示す場合、パスの後にコロン(「:」)で区切って 示します。例えば、 /localhost/comp0.rtc:data は comp0.rtc というRTコンポーネントの data というポートを示します。
新しいポートを作るコマンドもあります。この場合、オプションをパスに追加 することができます。使えるオプションは作られるポートの名前とフォーマッタ です。指定方法は以下の通りです:
path:port.name#formatter
例:
/localhost/blurg.host_cxt/comp0.rtc:input.stuff#a_printer
作られるポートの名前は stuff で、データは a_printer という関数で ターミナルに表示するように指定してます。( a_printer の関数はPythonが利 用可能な場所に存在する必要があります。普通はユーザがモジュールで提供します。) 作られたポートは comp0.rtc の input というポートに接続します。
「name」という部分は必須ではありません。書いていない場合は「.」文字も 書かないでください。例:
/localhost/blurg.host_cxt/comp0.rtc:input#a_printer
「formatter」という部分は必須ではありません。書いていない場合は「.」文字も 書かないでください。例:
/localhost/blurg.host_cxt/comp0.rtc:input.stuff
- RTCTREE_ORB_ARGS
- ORBを作る時に渡す変数です。セミコロンで区切ります。必須ではありません。
- RTCTREE_NAMESERVERS
- RTCツリーを作る時に参照するネームサーバのアドレスです。アドレスをセミ コロンで区切ります。リストされたアドレスはすべてRTCツリーに追加して rtshellで見ることができるようになります。必須ではありません。
- RTSH_CWD
- rtshellの現在のワーキングディレクトリ。rtshellが自動的に設定します。 設定しないでください。
普通、ユーザが設定する変数は RTCTREE_NAMESERVERS のみです。よく使うネ ームサーバを設定しておくと便利です。例えば、Bashシェルの場合、以下のコマンド は localhost 、 192.168.0.1:65346 および example.com にあるネーム サーバをいつもrtshellで利用できるようにします。
$ export RTCTREE_NAMESERVERS=localhost;192.168.0.1:65346;example.com
成功の場合はゼロを返します。失敗の場合はゼロではない値を返します。
デバグ情報とエラーは stderr に出します。
$ rtdoc /localhost/ConsoleOut0.rtc
ConsoleOut0.rtc のドキュメンテーションを標準出力に表示します。
$ rtdoc /localhost/ConsoleOut0.rtc > doc.html
ConsoleOut0.rtc のドキュメンテーションを doc.html というファイルに 保存します。
$ rtdoc /localhost/ConsoleOut0.rtc -f rst
ConsoleOut0.rtc のドキュメンテーションをreStructuredTextフォーマット に表示します。
$ rtdoc /localhost/ConsoleOut0.rtc -f latex > doc.tex && rubber -d doc.tex
ConsoleOut0.rtc のドキュメンテーションを rubber ツールによってPDF に保存します。
rtconf (1), rubber (1)