Getting started

Configuration

ros_msg_reference_version

The used ROS version to use when referencing to default message types, e.g. 'kinetic' or 'melodic'. It defaults to 'melodic' and is set to 'kinetic' for this documentation.

ros_add_package_names

Can be set to False to prevent package names from showing in message, service, or action type descriptions. Defaults to True.

Directives

.. ros:package:: package

Similar to the Python domain’s .. py:module:: directive. It will not output any nodes, but serves to set the context’s ROS package and will produce a hyperlink target and an index entry for package. Defined packages can be referenced with :ros:pkg:`package`.

Options:
  • noindex – Prevents adding the package to the index, basically turns this directive into ros:currentpackage.
  • deprecated – Flags this package as deprecated. This wil show up in the index.
.. ros:currentpackage:: package

Similar to the Python domain’s .. py:currentmodule:: directive. It will not produce any nodes nor an index entry but will set the context’s ROS package such that Sphinx knows that we are documenting stuff in that package.

This directive has no options.

.. ros:message:: message

Can be used to describe a message type definition. It will create an index entry and a hyperlink target for this message type. It will also output nodes to describe the message.

Options:
  • noindex – Prevents adding the message to the index and creating a hyperlink target node.
  • deprecated – Flags this message as deprecated. This wil show up in the index.

Two flags are recognized in this directive’s content: :msg_param <name>: and :msg_paramtype <name>:. The former defines a parameter that is contained in the message, the latter defines the same parameter’s type. All parameters will be grouped in a list.

.. ros:service:: service

Can be used to describe a service type definition. It will create a hyperlink target for the service type. It will also output nodes to describe the service.

Options:
  • noindex – Prevents creating a hyperlink target node for the service.
  • deprecated – Flags this service as deprecated.

Four flags are recognized in this directive’s content: :req_param <name>: and :req_paramtype <name>: work similar to the flags of the message directive, but they add parameters to the service’s request. :resp_param <name>: and :resp_paramtype <name>: do the same for the service’s response.

.. ros:action:: action

Can be used to describe a action type definition. It will create a hyperlink target for the action type. It will also output nodes to describe the action.

Options:
  • noindex – Prevents creating a hyperlink target node for the action.
  • deprecated – Flags this action as deprecated.

Six flags are recognized in this directive’s content: :goal_param <name>: and :goal_paramtype <name>: work similar to the flags of the message directive, but they add parameters to the action’s goal. :result_param <name>: and :result_paramtype <name>: do the same for the action’s result. :feedback_param <name>: and :feedback_paramtype <name>: do the same for the action’s feedback.

Roles

:ros:pkg:

Can be used to reference a defined package.

:ros:msg:

Can be used to reference a defined message type. Adding the ~ prefix to the message name will let it print only the message name and not the package name. First it is checked if the message is one of the ROS primitive message types (bool, int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, float64, string, time, duration). If so, it will not link anywhere. If it is of the type Header or it is a message in one of the default ROS message packages, it will link to the proper documentation, keeping into account the ROS version set by ros_msg_reference_version.

The default ROS message packages that are correctly handled as of now are: std_msgs, geometry_msgs, and sensor_msgs.

:ros:srv:

Can be used to reference a defined service type. Adding the ~ prefix to the service name will let it print only the service name and not the package name.

:ros:act:

Can be used to reference a defined action type. Adding the ~ prefix to the action name will let it print only the action name and not the package name.

Package example

Source
.. ros:package:: sphinx_ros_example

###################################
The ``sphinx_ros_example`` package.
###################################

.. contents::
  :local:
  :depth: 1

The :ros:pkg:`sphinx_ros_example` package contains all sorts of ROS objects,
purely for example purposes. Objects can be referenced just like the familiar
default Sphinx references, e.g. :ros:msg:`sphinx_ros_example/Foo` will link
the proper message, and :ros:srv:`sphinx_ros_example/Bar` will link to the
proper service. We can also use the ``~`` to prevent displaying the package
name, e.g. :ros:msg:`~sphinx_ros_example/Foo` still points to the right
message.

:Author: `J. Doe <j.doe@mail.com>`_

:Maintainer: `J. Doe <j.doe@mail.com>`_

:Links: * `Repository <http://github.com/user/repo>`_
        * `Bugtracker <http://github.com/user/repo/issues>`_

:Version: 1.2

:License: MIT


************
Dependencies
************

:Build: * :ros:pkg:`message_generation`
        * :ros:pkg:`std_msgs`

:Build export: :ros:pkg:`std_msgs`

:Build tool: :ros:pkg:`catkin`

:Execution: * :ros:pkg:`message_runtime`
            * :ros:pkg:`std_msgs`


********
Messages
********

.. ros:message:: Foo

  :msg_param header: Header of the message.
  :msg_paramtype header: :ros:msg:`Header`
  :msg_param pose: The 3D pose of the foo that is detected.
  :msg_paramtype pose: :ros:msg:`geometry_msgs/Pose`
  :msg_param color: The color of the foo.
  :msg_paramtype color: :ros:msg:`string`


********
Services
********

.. ros:service:: Bar

  :req_param one_way: The request parameter.
  :req_paramtype one_way: :ros:msg:`sphinx_ros_example/Foo`
  :resp_param or_another: The response parameter.
  :resp_paramtype or_another: :ros:msg:`int8`
  :resp_param highway: The correct way.
  :resp_paramtype highway: :ros:msg:`uint16`


********
Actions
********

.. ros:action:: FooBar

  :goal_param setpoint: The setpoint to reach.
  :goal_paramtype setpoint: :ros:msg:`geometry_msgs/Point`
  :result_param steady_state_error: Error between achieved point and setpoint.
  :result_paramtype steady_state_error: :ros:msg:`geometry_msgs/Point`
  :feedback_param tracking_error: Error between ideal trajectory and current
                                  trajectory.
  :feedback_paramtype tracking_error: :ros:msg:`geometry_msgs/Point`
  :feedback_param power: Current power usage per joint.
  :feedback_paramtype power: :ros:msg:`float32[]`

Indices

These indices are generated by this Sphinx extension. They are autogenerated and can be referenced with :ref:`ros-pkgindex` and :ref:`ros-msgindex` respectively.