You're reading the documentation for the non-stable development version of MoveIt 2. For the stable, released version, please have a look at Humble.
How to Cross-Reference Content
This is a primer on how to successfully link to other documents on this website and the API.
There are many and maybe too many different ways to reference content and for new contributors it can be hard to understand what method to use. Some methods may even work locally but then silently fail to create functional links on the deployed website. For that reason, we are requesting contributors to only use the suggested Sphinx roles for cross-referencing content on this website.
Linking to documents and sections using Sphinx’s
:ref:ids generated from the autosectionlabel extension
Referencing the C++ API using the
:cpp_api:role from the doxylink extension
Linking to other Documents and Sections
Sphinx provides the
:ref: roles for cross-referencing content and it’s best to stick to them to ensure compatibility with other Sphinx extensions and multi-distro support.
For linking to other documents, you can use the
:doc: role like this: Getting Started (
:ref: role accepts ids that link to explicit targets on a page.
For convenience, we have enabled the Sphinx extension autosectionlabel which creates unique and human-readable reference targets for all sections.
Sections in all documents can be linked by providing the document path and the section title like this (
:ref:`like this <doc/tutorials/getting_started/getting_started:Install ROS 2 and Colcon>`).
Note that the
:doc: role requires absolute paths to start with a
/ while the autosectionlabel extension builds
:ref path labels without it.
Referencing the API Documentation
The API pages are generated using Doxygen and not Sphinx which means that
:ref: roles are not able to find any API pages.
We are using doxylink and the custom
:cpp_api: role for generating links to the API pages from symbols.
Here are some examples, take note that some links use titles and some not:
functions and members:
:cpp_api:`RobotModel::getName() <moveit::core::RobotModel::getName>`-> RobotModel::getName()
:cpp_api:`moveit::core::RobotModel::enforcePositionBounds(double *state) const`-> moveit::core::RobotModel::enforcePositionBounds(double *state) const
:cpp_api:`RobotModel::root_link_ <moveit::core::RobotModel::root_link_>`-> RobotModel::root_link_
If you are unsure about how to link certain symbols, you can find all Doxygen references inside the
The file is located inside
build/html/<branch>/api/ depending on the build type.
Do’s and Don’ts
Cross-reference as much as possible, especially code
Provide meaningful titles for links or shorten API symbols to improve readability
Use raw URLs for referencing tutorials or the API
Link to GitHub source files, prefer the Doxygen pages