This page describes useful macros specific to ros.org. The source code of these macros can be found in the roswiki repository on github.

For generic moinmoin macros, see HelpOnMacros.

PackageHeader

This automatically generates the package header that you see on all package pages.

This relies on manifest.yaml files having been generated to http://docs.ros.org/{distro}, where {distro} is a ROS distribution like indigo or jade, e.g. http://docs.ros.org/jade.

Usage:

<<PackageHeader(PACKAGE)>>

{{{#!wiki version fuerte_and_older
A fuerte and older specific note here.
}}}

{{{#!wiki version groovy
A groovy specific note here.
}}}

{{{#!wiki version hydro_and_newer
A hydro and newer specific note here.
}}}

Example: roscpp

By default, the package header macro generates tabs for each distro of ROS currently supported. It also automatically includes support for version specific text to be included on each wiki page. You can also pass an optional distro argument to the macro if you'd only like a header generated for a specific distribution.

<<PackageHeader(PACKAGE DISTRO)>>

StackHeader

This automatically generates the stack header that you see on all stack pages.

This relies on stack.yaml files having been generated to http://www.ros.org/doc/

Usage:

<<StackHeader(STACK)>>

{{{#!wiki version fuerte_and_older
A fuerte specific note here.
}}}

{{{#!wiki version groovy
A groovy specific note here.
}}}

{{{#!wiki version hydro_and_newer
A hydro and newer specific note here.
}}}

Example: geometry

By default, the stack header macro generates tabs for each distro of ROS currently supported. It also automatically includes support for version specific text to be included on each wiki page. You can also pass an optional distro argument to the macro if you'd only like a header generated for a specific distribution.

Usage

<<StackHeader(STACK DISTRO)>>

GitHubIssues

The GitHubIssues macro lets you link to the active issue tracker easily.

<<GitHubIssues(github_organization/github_repository)>>

Example:

<<GitHubIssues(ros/ros)>> 

Use GitHub to report bugs or submit feature requests. [View active issues]

A second argument allows for specifying a component name. Example:

<<GithubIssues(ros/ros rosmake)>> 

Use GitHub to report bugs or submit feature requests. Please use 'rosmake:' at the beginning of the title. [View active issues]

GoogleGroups

Embed Google Groups into a wiki page.

Example:

<<GoogleGroups(ros-sig-embedded)>>

MsgSrvDoc

This automatically creates a list of messages, services and actions and links to their generated documentation. Usage:

<<MsgSrvDoc(package/name)>>

Example: std_msgs

MsgLink

This automatically creates a link to the msg in the ROS code API documentation. Usage:

<<MsgLink(package/name)>>

Example:

<<MsgLink(nav_msgs/OccupancyGrid)>>

nav_msgs/OccupancyGrid

SrvLink

This automatically creates a link to the msg in the ROS code API documentation. Usage:

<<SrvLink(package/name)>>

Example:

<<SrvLink(nav_msgs/GetMap)>>

nav_msgs/GetMap

Stack Navi

This macro uses the stack.xml to display the stack description and create navigation bar into the stack packages. Usage:

<<StackNavi(stack)>>

Example:

<<StackNavi(foote_photo_management)>> 

Newly proposed, mistyped, or obsolete stack. Could not find stack "foote_photo_management" in rosdoc

IncludeCSTemplate

This macro takes the keys at the top of the page and turns them into clearsilver variables that can be operated on using the clearsilver templating commands. In the case of tutorials the keys are used in the TutorialCSHeaderTemplate.

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

Vimeo

This macro allows you to embed youtube video into the wiki page using the video key Usage:

<<Vimeo(key)>>

Example:

<<Vimeo(61568492)>>

Youtube

This macro allows you to embed youtube video into the wiki page using the video key Usage:

<<Youtube(key)>>

Example:

<<Youtube(bNtm6_FBJp8)>>

To suppress the "related videos" from showing at the end of the video, you can also do this:

<<Youtube(bNtm6_FBJp8&rel=0)>>

Version

This macro allows you to consistently report a version number for a particular package, stack, API, or otherwise. If the version macro is given arguments you will see a highlighted tag. If given no arguments you will see a number of version buttons labelled with the names of ROS releases appear. These can be used to toggle between versioned text in your wiki page.

Usage

Arguments:

<<Version(ROS hydro)>>

my_api() New in ROS hydro

No arguments:

<<Version()>>

Welcome to a demo of a cool API tool

{{{#!wiki version groovy

This is my groovy API.  It's old

}}}

{{{#!wiki version jade

This is my jade API.  It's new and awesome

It has wiki formatting and '''everything'''!!!
}}}

{{{#!wiki version indigo jade
You can name multiple versions to get the same text to show for all the named versions - in this case, indigo and jade.
}}}

{{{#!wiki version hydro_and_newer
You can also match all older and newer distributions. This block will show in hydro, indigo, jade, and all future ROS distros.
}}}

This text is relevant to everyone

{{{#!wiki version fuerte_and_older
As well you can match all older distros.

fuerte and older specific stuff.  
}}}

melodic noetic   Show EOL distros: 

Welcome to a demo of a cool API tool

This text is relevant to everyone

Note: In case you are using embedded code in the version specific text ( { { { some code } } } ), you have to add an extra { and } to the wiki version enclosure.

Switch Entire Pages by Version

In order to have more than a single block of text switched by the Version macro, you can put entire pages into sub-pages and then use the Include() macro to switch between them. For example, if you have a page like my_package/Tutorials/Tut1, and you want different tutorials for different versions, you can do something similar to the following:

<<Version()>>

{{{#!wiki version cturtle
<<Include(my_package/Tutorials/Tut1/cturtle)>>
}}}

{{{#!wiki version diamondback
<<Include(my_package/Tutorials/Tut1/diamondback)>>
}}}

{{{#!wiki version electric
<<Include(my_package/Tutorials/Tut1/electric)>>
}}}

Note: The included page must not contain invocation of the PackageHeader / StackHeader macros. This would result in duplicating the header which break the JavaScript functionality they provide (e.g. the ROS distro buttons and the documentation status do not work any more).

Insert ROS distribution name

A JavaScript powered companion to the Version macro, that replaces the string \$ROS_DISTRO with the lower-case name of the ROS version currently selected on the page. This can be useful for presenting instructions which are identical between distros, apart from the exact name of the distro, for example:

<<Version()>>
{{{
$ source /opt/ros/\$ROS_DISTRO/setup.bash
}}}

Results in:

$ source /opt/ros/$ROS_DISTRO/setup.bash

The text is automatically updated based on the currently selected ROS version.

Buildsystem

You can use this macro to switch sections on catkin/rosbuild.

You can flag sections like this:

<<Buildsystem(catkin)>>
{{{
catkin_make
}}}

<<Buildsystem(rosbuild)>>
{{{
rosmake
}}}

Which looks like this rendered:

catkin specific

catkin_make

rosbuild specific

rosmake

You can also have togglable sections and/or whole pages:

<<Buildsystem()>>

{{{{#!wiki buildsystem catkin
{{{
catkin_make
}}}
}}}}

{{{{#!wiki buildsystem rosbuild
{{{
rosmake
}}}
}}}}

Which looks and behaves like this:

catkin rosbuild

catkin_make

rosmake

Note that if you have multiple sections, the buttons control allsections at once,so maybe it is best to only have one directive <<Buildsystem()>> per page, even if there are multiple sections.

TutorialChain

This macro will display a list or chain of tutorials in a number list. If you have tutorials A, B, and C where A says B is the next tutorial and B says C is the next tutorial, then calling:

<<TutorialChain(path/to/TutorialA)>>

Will produce a list of Tutorials. This macro is useful for a Tutorial landing page. It was created to replace the old FullSearch... Tutorial macro which was causing performance issues on the wiki.

Examples

ROS/Tutorials catkin/Tutorials

CodeRef

Often you will see tutorials first listing a whole file and then few snippets from it. To correctly display lines, avoid mistakes from copy & paste, the code should be listed only once, and referenced later. To do so, start your code block like this:

{{{
#!foo block=myblockname

some more text
on several lines
and even more
...

The newline after the first {{{ is important. Choose any name you want for myblockname. Then, later in the wiki, you can cite parts of that code using:

<<CodeRef(myblockname,3,5)>>

Becomes:

some more text
on several lines

Note that the codeblock needs to have been saved at least once for the preview to work! Line numbers only show if you use a language recognized by the wiki.

AnswersSearch

Use this macro to search for a list of tags on anwsers.ros.org

<<AnswersSearch(text to display, drivers, hardware)>>

Becomes: text to display

Markdown

Use this macro to render Markdown within this wiki. Note that relative links may not work as intended.

<<Markdown(https://raw.githubusercontent.com/locusrobotics/robot_navigation/master/dwb_critics/README.md)>>

This will fetch the text from the specified URL and render it as Markdown. See rendered example