NOTE: This repository is a new fork from the MoveIt 1 tutorials and needs your help with porting old tutorials to ROS 2. To claim a tutorial to support the port of, see the Issues list. Thanks!
See the live MoveIt 2 tutorials here
This is the primary documentation for the MoveIt project. We strongly encourage you to help improve MoveIt's documentation. Please consider reading the guidelines below for writing the best documentation and tutorials. However, if you are uncomfortable with any of the approaches, simply adding documentation text to your pull requests is better than nothing.
These tutorials use the reStructuredText format commonly used in the Sphinx "Python Documentation Generator". This unfortunately differs from the common Markdown format, but its advantage is that it supports embedding code directly from source files for inline code tutorials.
All content in this repository is open source and released under the BSD License v3. Each individual source code file should contain a copy of the license.
This repository is currently built automatically by Github Actions:
- main:
- main:
- galactic:
- galactic:
- foxy: (Foxy)
- foxy: (Foxy)
- foxy:
(Foxy) - foxy: Github Pages: (Foxy)
An issue has been created for each tutorial to be ported to Foxy. At the top of each tutorial there is a tag: ":moveit1:", remove the tag after the tutorial has been successfully updated.
Below are some links to help with the ports.
mainlatest, changes should target this branch
Follow the MoveIt 2 Source Build instructions to setup a colcon workspace with moveit2 from source.
Open a command line to your your moveit2 colcon workspace:
cd $COLCON_WS/src
Download Moveit2_tutorials Source Code
git clone https://github.com/ros-planning/moveit2_tutorials.git
vcs import < moveit2_tutorials/moveit2_tutorials.repos
rosdep install -r --from-paths . --ignore-src --rosdistro rolling -y
Configure and build the workspace:
cd $COLCON_WS
colcon build --event-handlers desktop_notification- status- --cmake-args -DCMAKE_BUILD_TYPE=Release
If you want to test the tutorials by generating the html pages locally on your machine, you can use the build_locally script by issuing the following commands in the root of the moveit2_tutorials package:
export ROS_DISTRO=rolling # 20.04
cd $COLCON_WS/src/moveit2_tutorials
source /opt/ros/$ROS_DISTRO/setup.bash
./build_locally.sh
The local website <LOCAL_PACKAGE_PATH>/build/html/index.html should automatically open in your web browser.
- noinstall skip the dependencies install step to speed up the script
- loop automatically rebuild the html if a change is detected
We rely on the community to keep these tutorials up to date and bug free. If you find an issue with the tutorials please open an issue on GitHub or open a PR with proposed changes.
Code Formatting
- These tutorials use the same style guidelines as the MoveIt project. When modifying or adding to these tutorials, it is required that code is auto formatted using clang-format. To check and apply our style guidelines we use pre-commit.
- Tutorials should exemplify best coding practices. If a contribution wouldn't pass review in the MoveIt project, then it shouldn't pass review in the tutorials.
- Relevant code should be included and explained using the
.. tutorial-formatter::tag. - Irrelevant code should be excluded from the generated html using the
BEGIN_TUTORIAL,END_TUTORIAL,BEGIN_SUB_TUTORIAL, andEND_SUB_TUTORIALtags. - Whenever possible, links should be created using the
extlinksdictionary defined inconf.py. - All demo code should be runnable from within the
moveit2_tutorialspackage. - Python code should be run using
ros2 run.
Style
- Each tutorial should be focused on teaching the user one feature or interface within MoveIt.
- Tutorials should flow from show to tell with videos and demos at the beginning followed by explanations.
- New tutorials should match the formatting, style and flow of existing tutorials whenever possible.
pre-commit
pre-commit is a tool that is used in moveit2_tutorials to check and apply style guidelines automatically. To install pre-commit into your system:
pip3 install pre-commit
Then under moveit2_tutorials directory install the git hooks like this:
cd $COLCON_WS/src/moveit2_tutorials && pre-commit install
With this pre-commit will automatically run and check a list of styling including clang-format, end of files and trailing whitespaces whenever you run git commit. To run pre-commit any time other than git commit:
cd $COLCON_WS/src/moveit2_tutorials && pre-commit run -a
The standard way to include an image in reStructuredText is
.. image:: filename.png
:width: 700px
This assumes that filename.png is in the same folder as the source .rst file. Images linked in this way will automatically be copied to the appropriate folder in the build.
Do not include animated gifs as the file format leads to very large files. Use a video format like webm and see the section on local video below.
You can embed video with raw html, like in this example from the Pick and Place Tutorial.
.. raw:: html
<div style="position: relative; padding-bottom: 5%; height: 0; overflow: hidden; max-width: 100%; height: auto;">
<iframe width="700px" height="400px" src="https://www.youtube.com/embed/QBJPxx_63Bs?rel=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>
This includes Youtube's suggested embed html.
To embed a video that is included in this repository, you also will use raw html, like this example from the Quickstart in RViz tutorial.
.. raw:: html
<video width="700px" controls="true" autoplay="true" loop="true">
<source src="../../../_static/videos/rviz_joints_nullspace.webm" type="video/webm">
The joints moving while the end effector stays still
</video>
Note that the video file is in the _static/videos folder instead of the same folder.