Getting started

Configuration

ros_msg_reference_version

The used ROS version to use when referencing to default message types, e.g. 'kinetic' or 'melodic'.

Default

ros_msg_reference_version = 'melodic'
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.

Default

ros_add_package_names = True
ros_api_msg_packages

This is a list of default ROS packages that contain message or service types that are referenced. This enables automatically linking to the ROS documentation. It should be a list of strings containing package names.

Default

ros_api_msg_packages = ['std_msgs', 'geometry_msgs', 'sensor_msgs']

New in version 0.2.

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.

.. ros:node:: node

Can be used to describe a ROS node.

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

Three pairs of flags are recognized in this directive’s content: :publisher <topic>: <description> and :publisher_msg_type <topic>: <msg_type>, :subscriber <topic>: <description> and :subscriber_msg_type <topic>: <msg_type>, :service <name>: <description> and :service_type <name>: <srv_type>. With the first, publishers can be documented with the topics they publish on, as well as the message type that the topic expects. The second acts similar for subscribers, and with the last you can document services that the node provides, with their name and required service type.

New in version 0.2.

autoros

.. ros:automessage:: message

Todo

Add description.

New in version 0.2.

.. ros:autoservice:: service

Todo

Add description.

New in version 0.2.

.. ros:autoaction:: action

Todo

Add description.

New in version 0.2.

.. ros:autopackage:: package

New in version 0.2.

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.

Changed in version 0.2: The default ROS message packages can be set with ros_api_msg_packages.

: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.

:ros:node:

Can be used to reference a defined ROS node. Addding the ~ prefix to the node name will let it print only the node name and not the package name.

New in version 0.2.

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[]`


*****
Nodes
*****

.. ros:node:: bar_foo

  :publisher /bar/foo: Publishes the foo to the bar.
  :publisher_msg_type /far/boo: :ros:msg:`geometry_msgs/Point`
  :subscriber /bar/foo: Subscribes to the bar, to listen for foo.
  :subscriber_msg_type /far/boo: :ros:msg:`geometry_msgs/Point`
  :service /set_foo: Sets the foo.
  :service_type /set_foo: :ros:srv:`~sphinx_ros_example/Bar`

Indices

This Sphinx extension adds two autogenerated indices. One for the documented packages and one for the documented message types.

With the html builder, these can be referenced with :ref:`ros-pkgindex` and :ref:`ros-msgindex` respectively.