These are the tutorials for MoveIt 1, for MoveIt 2 see MoveIt 2 Tutorials
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 two systems. Github Actions builds the documentation for Noetic, and ROS Build Farm builds the documentation for older versions:
indigo-devel
usage is discouragedkinetic-devel
stablemelodic-devel
stablemaster
latest, changes should target this branchIf you want to test the tutorials by generating the HTML pages locally on your machine, you can use the build_locally
script.
Run in the root of the moveit_tutorials package:
export ROS_DISTRO=kinetic # 16.04
export ROS_DISTRO=melodic # 18.04
export ROS_DISTRO=noetic # 20.04
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.
For deploying documentation changes to the web, Section 3 of the rosdoc_lite wiki says that "rosdoc_lite is automatically run for packages in repositories that have rosinstall files listed in the rosdistro repository." This is done about once every 24 hours, overnight.
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 the proposed changes.
Code Formatting
.. tutorial-formatter::
tag.BEGIN_TUTORIAL
, END_TUTORIAL
, BEGIN_SUB_TUTORIAL
, and END_SUB_TUTORIAL
tags.extlinks
dictionary defined in conf.py
.moveit_tutorials
package.rosrun
.Style
pre-commit
pre-commit is a tool that is used in moveit_tutorials
to check and apply style guidelines automatically. To install pre-commit into your system:
pip3 install pre-commit
In your catkin workspace, under themoveit_tutorials
directory you can install the git hooks like this:
cd $CATKIN_WS/src/moveit_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 a pre-commit at any time other than git commit
you can use the following command:
cd $CATKIN_WS/src/moveit_tutorials && pre-commit run -a
./doc/ <>
directory.index.rst
in the root directory.moveit_tutorials/doc/
└── <tutorial_name>/
├── <tutorial_name>_tutorial.rst
├── CMakeLists.txt
├── package.xml
├── setup.py
├── images/
│ └── <tutorial_name>_<image_description>.png
├── include/
│ └── <tutorial_name>/
│ └── <include_header>.h # Any custom C++ library header files
├── launch/
│ └── <tutorial_name>_tutorial.launch
├── src/
│ ├── <tutorial_name>_tutorial.cpp # Main C++ executable
│ ├── <include_source>.cpp # Custom C++ library source files
│ └── <tutorial_name>/
│ ├── __init__.py
│ ├── <tutorial_name>_tutorial.py # Main Python executable
│ └── <python_library>.py # Custom Python libraries
└── test/ # Ideally tutorials have their own integration tests
├── <tutorial_name>_tutorial.test # Launch file for tests
├── <tutorial_name>_tutorial_test.py # Python tests for tutorial
└── <tutorial_name>_tutorial_test.cpp # C++ tests for tutorial
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 the 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 code.
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" nocontrols="true" autoplay="true" loop="true">
<source src="https://github.com/moveit/moveit_tutorials/raw/master/./../_static/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
folder instead of the same folder.