• Stars
    star
    144
  • Rank 255,590 (Top 6 %)
  • Language
    CSS
  • License
    BSD 3-Clause "New...
  • Created almost 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A sphinx-based centralized documentation repo for MoveIt 2

MoveIt Tutorials

Live tutorials here

This is the primary documentation for the MoveIt project.

Build Status

This repository is built and deployed automatically by GitHub Actions:

  • Rolling (main): CI Format Deploy
  • Humble: CI Format Deploy

Contributing

We strongly encourage you to help improve MoveIt's documentation. Please consider helping improve the tutorials, port old ones from ROS 1, and write new tutorials. We recommend you read the quality standards below as well as the How to Write a MoveIt Tutorial page.

If you find an issue with the tutorials you are not able to fix yourself, please open an issue on GitHub or open a PR with proposed changes.

Helping with Porting Tutorials to ROS 2

An issue has been created for each tutorial to be ported to ROS 2. 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.

MoveIt Tutorials Source Build

Follow the MoveIt Source Build instructions to set up a colcon workspace with MoveIt from the source.

Open a command line to your colcon workspace:

cd $COLCON_WS/src

Download the MoveIt 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

Build HTML Pages Locally

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.

Optional build_locally Settings

  • noinstall skip the dependencies install step to speed up the script
  • loop automatically rebuilds the HTML if a change is detected

Formatting and Style

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.

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 the 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, and END_SUB_TUTORIAL tags.
  • Whenever possible, links should be created using the extlinks dictionary defined in conf.py.
  • All demo code should be runnable from within the moveit2_tutorials package.
  • 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 the 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

Including Images and Videos

Images

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.

External Documentation

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.

YouTube and other External Video

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.

Local Video

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 move while the end effector stays still
    </video>

Note that the video file is in the _static/videos folder instead of the same folder.

External Documentation on <video> tag

License

All content in this repository is open source and released under the BSD License v3. Each source code file should contain a copy of the license.

More Repositories

1

moveit

🤖 The MoveIt motion planning framework
C++
1,621
star
2

moveit2

🤖 MoveIt for ROS 2
C++
1,014
star
3

moveit_tutorials

A sphinx-based centralized documentation repo for MoveIt
HTML
464
star
4

moveit_task_constructor

A hierarchical multi-stage manipulation planner
C++
172
star
5

moveit_visual_tools

Helper functions for displaying and debugging MoveIt! data in Rviz via published markers
C++
146
star
6

moveit_calibration

Hand-eye calibration tools for robot arms.
C++
124
star
7

panda_moveit_config

The Panda robot is the flagship MoveIt integration robot
CMake
99
star
8

moveit_grasps

Geometric grasping generator library for cuboids
C++
89
star
9

moveit_ros

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
69
star
10

moveit_resources

URDFs, meshes, and config packages for MoveIt testing
Python
61
star
11

geometric_shapes

Representation of geometric shapes
C++
57
star
12

moveit_pr2

MoveIt! Packages for PR2
C++
51
star
13

moveit_robots

MoveIt! configurations for different robots
C++
48
star
14

moveit_msgs

ROS messages used by MoveIt
CMake
46
star
15

moveit.ros.org

This is the MoveIt website
HTML
37
star
16

warehouse_ros

Data persistence for ROS using MongoDB
C++
31
star
17

moveit_core

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
30
star
18

moveit_example_apps

Demonstrator applications for using MoveIt with full robotic setups
Python
24
star
19

warehouse_ros_mongo

Implementation of warehouse_ros using MongoDB
C++
17
star
20

moveit_planners

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
16
star
21

moveit_ci

Continuous Integration for MoveIt
Shell
16
star
22

moveit_advanced

C++
15
star
23

moveit_drake

Experimental repository for Moveit2 - Drake integration
C++
15
star
24

warehouse_ros_sqlite

Data persistence for ROS using SQLite
C++
13
star
25

moveit_plugins

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
12
star
26

srdfdom

Semantic Robot Description Format
C++
12
star
27

moveit_ikfast

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
12
star
28

moveit_commander

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
Python
11
star
29

moveit_kinematics_tests

DEPRECATED, MOVED TO https://github.com/ros-planning/moveit
C++
11
star
30

moveit_setup_assistant

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
8
star
31

random_numbers

Routines for random number generation
C++
8
star
32

moveit_docs

DEPRECATED - see https://github.com/ros-planning/moveit.ros.org
CSS
5
star
33

stomp_moveit

STOMP support for MoveIt - ROS 2
C++
4
star
34

moveit_metapackages

DEPRECATED - see https://github.com/ros-planning/moveit
CMake
2
star
35

moveit_experimental

THIS REPO HAS MOVED TO https://github.com/ros-planning/moveit
C++
1
star
36

moveit2_packages

1
star
37

moveit_benchmark_resources

Configurations and databases for setting up benchmarks with MoveIt
Python
1
star
38

moveit_visual_tools-release

1
star
39

py_binding_tools

Python binding tools for C++
C++
1
star