Indexer

This page describes the indexer used to maintain ROS.org. This is currently an 'experts-only' guide meant to enable maintainers to carry out the various duties of maintaining the index.

The Index (repos.rosinstall)

The main index is in rosdoc_rosorg/repos.rosinstall. It is currently a monolithic file pointing to the desire repository locations for the entire ROS universe.

Hudson job:

• rosdoc (updates the default documentation, wiki headers)
• rosbrowse_rosdoc (updates the index for "Browse Software")

Distro-specific indexes

(IN PROGRESS)

In rosdoc_rosorg/index, there are assets related to creating distribution-specific indexes. These run against the debian installs of released stacks. We do this for:

• performance reasons
• for 'rosmake' builder reasons (e.g. tf/opencv python documentation that requires built packages)

In the event that a debian install is not available for a released stack, but you still want to include it in the index, you can modify the related .rosinstall file to include it as an overlay.

Adding repositories to the index

Usually this is as simple as creating a rosinstall entry. There can be some complications:

SVN repository requires accepting certificate

• Do a local checkout of the repository and permanently accept the cert. Then find the certificate in .subversion/auth/svn.ssl.server and copy it into rosbrowse/certs. The chroots will copy these certs when they initialize.

rosbrowse_rosdoc

For performance/stability reasons, this job does not run in a chroot. On occassion, this state has to be erased if conflicting changes are made to the index or other problems occur. It is okay to blow away the rosdoc_checkout directory when this happens; it mainly means the next job will take longer (and may be incomplete until all repos are available).

Index assets

In doc/api , there is a tree of assets organized by package/stack/repository name. The following assets are created:

• repo.yaml : for repositories
• stack.yaml : for stacks
• manifest.yaml : for packages

Note that the above implementation allows a symbol to be a package, stack, and repository simultaneously.

TODO: notes on megamanifest/megastack YAML assets for Browse

In parallel, we are also creating distribution-specific assets in:

doc/<distro-name>/api

Used by

The indexer is used by several ROS tools:

• "Browse Software" php scripts (maintained by Morgan)

• roswiki macros (e.g. StackHeader)

• roslocate