diff --git a/README.md b/README.md index efb2870f49..cd49c40e22 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,16 @@ # MoveIt Tutorials [Live tutorials here](https://moveit.picknik.ai/) -*There are still some tutorials not fully ported from ROS 1, we could use your help! See the section below on Helping Port Tutorials. Thanks!* +This is the primary documentation for the MoveIt project. -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. +## Contributing -These tutorials use the [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html) 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. +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](https://moveit.picknik.ai/main/doc/how_to_contribute/how_to_write_tutorials.html) page. -All content in this repository is open source and released under the [BSD License v3](https://opensource.org/licenses/BSD-3-Clause). Each individual source code file should contain a copy of the license. - -This repository is currently built automatically by Github Actions: - -- main: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Amain) -- main: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Amain) -- galactic: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Agalactic) -- galactic: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Agalactic) -- foxy: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Afoxy) (Foxy) -- foxy: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Afoxy) (Foxy) -- foxy: [![Deploy](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml?query=branch%3Afoxy) (Foxy) -- foxy: [Github Pages](https://moveit.picknik.ai/): (Foxy) +If you find an issue with the tutorials you are not able to fix yourself, please [open an issue on GitHub](https://github.com/ros-planning/moveit2_tutorials/issues/new) 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. @@ -30,9 +20,6 @@ Below are some links to help with the ports. * [ament](https://index.ros.org/doc/ros2/Tutorials/Ament-CMake-Documentation/) * [rclcpp](http://docs.ros2.org/foxy/api/rclcpp/index.html) -## Versions - -- ``main`` latest, changes should target this branch ## MoveIt Tutorials Source Build @@ -42,7 +29,7 @@ Open a command line to your colcon workspace: cd $COLCON_WS/src -Download the MoveIt 2 Tutorials Source Code +Download the MoveIt Tutorials source code: git clone https://github.com/ros-planning/moveit2_tutorials.git vcs import < moveit2_tutorials/moveit2_tutorials.repos @@ -70,12 +57,10 @@ The local website ``/build/html/index.html`` should automati - *noinstall* skip the dependencies install step to speed up the script - *loop* automatically rebuild the html if a change is detected -## 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](https://github.com/ros-planning/moveit2_tutorials/issues/new) or open a PR with proposed changes. - ### Formatting and Style +These tutorials use the [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html) 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](http://moveit.ros.org/documentation/contributing/code/) as the MoveIt project. When modifying or adding to these tutorials, it is required that code is auto formatted using [clang-format](http://moveit.ros.org/documentation/contributing/code/). To check and apply our style guidelines we use [pre-commit](https://pre-commit.com/). @@ -146,3 +131,23 @@ To embed a video that is included in this repository, you also will use raw html Note that the video file is in the `_static/videos` folder instead of the same folder. [External Documentation on <video> tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) + +## License + +All content in this repository is open source and released under the [BSD License v3](https://opensource.org/licenses/BSD-3-Clause). Each individual source code file should contain a copy of the license. + +## Build Status + +This repository is currently built automatically by Github Actions: + +- main: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Amain) +- main: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Amain) +- humble: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=humble)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Ahumble) +- humble: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=humble)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Ahumble) + +- galactic: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Agalactic) +- galactic: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Agalactic) +- foxy: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Afoxy) (Foxy) +- foxy: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Afoxy) (Foxy) +- foxy: [![Deploy](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml?query=branch%3Afoxy) (Foxy) +- foxy: [Github Pages](https://moveit.picknik.ai/): (Foxy) diff --git a/doc/how_to_contribute/how_to_write_tutorials.rst b/doc/how_to_contribute/how_to_write_tutorials.rst index bc8102ce67..703cad2f3b 100644 --- a/doc/how_to_contribute/how_to_write_tutorials.rst +++ b/doc/how_to_contribute/how_to_write_tutorials.rst @@ -4,7 +4,7 @@ How to Write a MoveIt Tutorial This guide explains how to write tutorials for the MoveIt documentation. Tutorials are one of the most useful contributions you can make because they are the first thing many new users see. This guide is intended for any contributor who wants to submit a new tutorial. -If you are looking for a how-to guide for using MoveIt, you can find one :doc:`here `. +There are many additional quality standards and how-tos for contributing to the tutorials located in this repository's `README `_. Learning Objectives ------------------- diff --git a/doc/tutorials/getting_started/getting_started.rst b/doc/tutorials/getting_started/getting_started.rst index de0e214dfe..44a99a6d4e 100644 --- a/doc/tutorials/getting_started/getting_started.rst +++ b/doc/tutorials/getting_started/getting_started.rst @@ -1,7 +1,7 @@ Getting Started =============== -This tutorial will install MoveIt 2 and create a workspace sandbox to run the tutorials and example robot. +Here we will setup your environment for best running the tutorials. This will create a Colcon workspace, download all of the latest MoveIt source code, and build everything from source to ensure you have the latest fixes and improvements. Install ROS 2 and Colcon ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -40,12 +40,15 @@ For tutorials you will need to have a :ros_documentation:`colcon `_. + +Setup Your Colcon Workspace +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Source the colcon workspace: :: source ~/ws_moveit2/install/setup.bash @@ -72,5 +82,5 @@ Optional: add the previous command to your ``.bashrc``: :: colcon workspace at a time, but we recommend it for simplicity. Next Step -^^^^^^^^^^ -:doc:`Visualize a robot with the interactive motion planning plugin for RViz ` +^^^^^^^^^ +Nice job! Next we will :doc:`Visualize a robot with the interactive motion planning plugin for RViz ` diff --git a/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst b/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst index 7d3f624a63..8874b2fce2 100644 --- a/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst +++ b/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst @@ -3,7 +3,7 @@ MoveIt Quickstart in RViz .. image:: rviz_plugin_head.png :width: 700px -This tutorial will quickly get you motion planning using MoveIt via RViz and the MoveIt plugin. Rviz is the primary visualizer in ROS and an incredibly useful tool for debugging robotics. The MoveIt Rviz plugin allows you to setup virtual environments (scenes), create start and goal states for the robot interactively, test various motion planners, and visualize the output. Let's go! +This tutorial will teach you how to create motion plans in MoveIt using RViz and the MoveIt Display plugin. Rviz is the primary visualizer in ROS and a very useful tool for debugging robotics. The MoveIt Display plugin allows you to setup virtual environments (planning scenes), create start and goal states for the robot interactively, test various motion planners, and visualize the output. Let's get started! Getting Started --------------- diff --git a/doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst b/doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst index 795ef2e4bb..2548a94ac3 100644 --- a/doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst +++ b/doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst @@ -1,7 +1,7 @@ Visualizing In RViz =================== -This tutorial will introduce you to a tool that can help you quickly understand what your MoveIt program is doing by rendering visualizations in RViz. +This tutorial will introduce you to a tool that can help you more easily understand what your MoveIt application is doing by rendering visualizations in RViz. Prerequisites ------------- diff --git a/doc/tutorials/your_first_project/your_first_project.rst b/doc/tutorials/your_first_project/your_first_project.rst index 8bb436f4ac..82fc4adbfb 100644 --- a/doc/tutorials/your_first_project/your_first_project.rst +++ b/doc/tutorials/your_first_project/your_first_project.rst @@ -1,7 +1,7 @@ Your First C++ MoveIt Project ============================= -This tutorial will quickly get you writing your first ROS project with MoveIt. +This tutorial will step you through writing your first C++ application with MoveIt. Prerequisites -------------