decyzy / moveit_tutorials

MoveIt 官方教程中文翻译版

MoveIt 中文教程（个人翻译版）

官方教程的 Master 分支的中文翻译，内容同步于 2021 年 2 月 26 日。

commit id：623dede236b006a8f1973ac336114d471ccaaa41

MoveIt 中文教程（个人翻译版）

已翻译章节

• 入门
• 在 RViz 中快速入门 MoveIt
• 移动群 Move Group 的 C++ 接口
• 移动群 Move Group 的 Python 接口
• MoveIt 命令行脚本
• 机器人模型 RobotModel 和机器人状态 RobotState
• 规划场景 PlanningScene
• 规划场景监控器 PlanningSceneMonitor
• 规划场景 PlanningScene 的 ROS API
• 运动规划 Motion Planning 的 API
• 运动规划管道 Motion Planning Pipeline

已知问题

• 中英文标点符号不统一
• 技术名词以直译为主

以下是原README

https://ros-planning.github.io/moveit_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. Travis builds the documentation for Melodic and ROS Build Farm builds the documentation for older versions:

• Github Pages + Travis: latest
• ROS Melodic Build Farm
• ROS Kinetic Build Farm

Versions

• indigo-devel usage is discouraged
• kinetic-devel stable
• melodic-devel stable
• master latest, changes should target this branch

Build Locally

If you want to test the tutorials by generating the html pages locally on your machine, you will first need to install the rosdoc_lite package, and then you can use the build_locally script. Run in the root of the moveit_tutorials package:

NOTE: rosdoc_lite is needed to run the build_locally.sh script!

export ROS_DISTRO=kinetic # 16.04
export ROS_DISTRO=melodic # 18.04
export ROS_DISTRO=noetic  # 20.04

sudo apt install ros-$ROS_DISTRO-rosdoc-lite
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.

ROS Build Farm Deployment

For deploying documentation changes to the web, Section 3 of 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.

Contributing

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.

Formatting and Style

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.
• 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 moveit_tutorials package.
• Python code should be run using rosrun.

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.

Directory Structure

• Each tutorial should live in its own subdirectory within the ./doc/ <> directory.
• Add your tutorial to index.rst in the root directory.
• Tutorials should use the following directory structure omitting unnecessary files and subdirectories:

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

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 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" nocontrols="true" autoplay="true" loop="true">
        <source src="../../_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.

External Documentation on <video> tag