Synopsis

rtdoc [options] <path>

Description

Print the documentation for an RT-Component.

Some RT-Components contain documentation internally, stored in hidden configuration sets. This tool prints that documentation in several convenient formats, including reStructuredText, HTML and LaTeX (suitable for compiling to PDF).

Options

-f FORMAT, --format=FORMAT
	Output format (one of rst, html or latex).
-g, --graph	Draw the component graph.

--version	Show program's version number and exit
-h, --help	Show a help message and exit
-v, --verbose	Output verbose information. [Default: False]

RT-Component documentation

To be compatible with this tool, an RT-Component must store its documentation in a configuration set called __doc__. Any parameters in this set that are not hidden are added to the documentation as sections.

The common sections are:

intro

An introduction to the component, giving a brief description of its purpose. (Title: Introduction.)

reqs

Pre-requisites for using the component, such as other software that must be installed. (Title: Pre-requisites.)

install

How to install the component. (Title: Installation.)

usage

How to launch and use the component. (Title: Usage.)

misc

Any other information important to using the component. (Title: Miscellaneous.)

changelog

A description of changes to the component since the previous versions. (Title: Changelog.)

In addition, a ports section and a config section are automatically created if the component has any ports or any configuration parameters in its default configuration set. Any other sections present in the __doc__ set will also be added to the documentation.

You can also set three parameters to add extra information to the documentation preamble:

__license__

The license of the component, such as GPL or BSD.

__contact__

Contact information, such as the author's email address.

__url__

The component's home page.

These parameters can be set either in the component source or in a configuration file loaded when the component is launched. Because in-source documentation increases the size of the component binary and memory requirements, it is recommended that the documentation be set in a configuration file, with the possible exception of brief contact and usage information.

For example, to set them in the source, use something similar to the following:

'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.',

By default, the sections are included in the following order:

intro, reqs, usage, ports, config, misc, changelog, [other sections]

This can be changed by setting the __order__ parameter in the __doc__ set. It must be set to a comma-separated list of parameter names, where each parameter name is a section in the documentation. For example:

'conf.__doc__.__order__', 'intro,ports,config,reqs,Another'

Any sections not mentioned in this parameter are added after the specified sections. The order in which they are added is not defined.

To document ports, add a description property to the port. For example:

self._inport.addProperty('description', 'This port receives stuff.')

To document configuration parameters, set the parameter in the __description__ set. For example:

'conf.default.param', '0',
'conf.__description__.param', 'A test parameter.',

Paths

rtshell uses paths to indicate objects in the RTC Tree. A path is the address of object. Name servers and naming contexts on name servers are considered directories. Managers and RT-Components are considered 'files'. As with the POSIX cat command, the path specified as an argument to commands is appended to the current rtshell working directory, which is stored in the RTCSH_CWD environment variable and changeable using the rtcwd command.

The available paths depend on the known name servers at the time the command is executed. This is a combination of the servers listed in the RTCSH_NAMESERVERS environment variable and the servers used in given paths.

For example, /localhost/comp0.rtc refers to the component named comp0.rtc registered on the name server at localhost. /localhost/manager/comp0.rtc refers to the component comp0.rtc in the directory manager on the localhost name server. ./comp0.rtc refers to that component in the current directory.

When specifying a port on an RT-Component, it should be placed after the path, separated by a colon. For example, /localhost/comp0.rtc:data refers to the port data on the component comp0.rtc.

Some commands that create new ports accept extra options in the paths, such as a name for the automatically generated port, or a formatter. The format for specifying these paths is:

path:port.name#formatter

For example:

/localhost/blurg.host_cxt/comp0.rtc:input.stuff#a_printer

This specifies that the automatically generated port should be named stuff, and the data type it handles should be printed using the a_printer function (which must be available, usually it is provided by the user in a loadable module). The port will be connected to the input port of the comp0.rtc component.

The name component is optional. If it is not present, neither should the . character be. For example:

/localhost/blurg.host_cxt/comp0.rtc:input#a_printer

The formatter component is optional. If it is not present, neither should the # character be. For example:

/localhost/blurg.host_cxt/comp0.rtc:input.stuff

Environment

RTCTREE_ORB_ARGS

A list of arguments, separated by semi-colons, to pass to the ORB when creating it. Optional.

RTCTREE_NAMESERVERS

A list of name server addresses, separated by semi-colons, to parse when creating the RTCTree. Each server in the list will be added to the tree, making it available for browsing with rtshell. Optional.

RTSH_CWD

The current working directory in the tree. Do not set this variable; it is set automatically by rtshell.

The only variable that should normally be set by the user is RTCTREE_NAMESERVERS. Set this to a list of name server addresses, separated by semi-colons, that rtshell should interact with. For example, in a Bash shell, the following command will set the known name serves to localhost, 192.168.0.1:65346 and example.com:

$ export RTCTREE_NAMESERVERS=localhost;192.168.0.1:65346;example.com

Diagnostics

Returns zero on success and non-zero on failure.

Verbose output and error messages are printed to stderr.

Examples

$ rtdoc /localhost/ConsoleOut0.rtc

Print the ConsoleOut0.rtc component's documentation to stdout.

$ rtdoc /localhost/ConsoleOut0.rtc > doc.html

Print the ConsoleOut0.rtc component's documentation to the file doc.html.

$ rtdoc /localhost/ConsoleOut0.rtc -f rst

Print the ConsoleOut0.rtc component's documentation in reStructuredText format.

$ rtdoc /localhost/ConsoleOut0.rtc -f latex > doc.tex &&
  rubber -d doc.tex

Make a PDF of ConsoleOut0.rtc's documentation, using the rubber tool to compile the LaTeX file.

See Also

rtconf (1), rubber (1)