diff --git a/source/About-analysis.rst b/source/About-analysis.rst new file mode 100644 index 00000000000..f0efc8dc3e3 --- /dev/null +++ b/source/About-analysis.rst @@ -0,0 +1,42 @@ +Analysis +======== + +Analyzing introspection data can help with improving it's performance. +This article summarizes the ROS developer tools and guidance available to help with analysis. + +**Area: analysis, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +Understanding what is happening inside your robot's software starts with introspection, which allows you to collect data. +Analysis tools in ROS help you go further by making sense of that data and revealing insights at the right level of detail. + +Core ROS packages: + +* `tracetools `_: Trace points for creating and debugging execution traces. +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: + +* `Plotjuggler `_: Visualization and analysis tool for inspecting, monitoring, and interpreting time-series data. +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + +Related content (placeholder) +----------------------------- + +More articles about analysis: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/About-builds.rst b/source/About-builds.rst new file mode 100644 index 00000000000..7069cb38890 --- /dev/null +++ b/source/About-builds.rst @@ -0,0 +1,59 @@ +Builds +====== + +The ability to work with multiple packages together is useful for developing complex robotics systems. +This article summarizes the ROS developer tools and guidance available to help with builds. + + +**Area: builds, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +Most ROS systems use multiple packages working together. +Build tools in ROS enable you to work with multiple packages in a single project and to share your packages with other members of the ROS community. + +Core ROS packages: + +* `colcon `_: Tool for creating and building a ROS workspace. + +* `ament_cmake `_: Build system for CMake-based packages in ROS. + +* `rosdoc2 `_: Tool for documenting a ROS package. +QUESTION FOR THE REVIEWER: IN THE SPREADSHEET THERE IS A QUESTION MARK NEXT TO THIS ENTRY. +DO WE NEED TO INCLUDE ros2doc IN THIS LIST? + +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: + +QUESTION FOR THE REVIEWER: ARE THERE ANY COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + +ROS build farm location +----------------------- + +The ROS build farm is critical infrastructure maintained by Open Robotics. +It supports the building of source and binary packages, as well as continuous integration, testing, and analysis for ROS packages: + +* ``_ + +Read more about ROS build farms: `ROS Build Farms — ROS 2 Documentation: Lyrical documentation `_ + +Related content (placeholder) +----------------------------- + +More articles about builds: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/About-introspection.rst b/source/About-introspection.rst new file mode 100644 index 00000000000..8ecfa951711 --- /dev/null +++ b/source/About-introspection.rst @@ -0,0 +1,53 @@ +Introspection +============= + +Sometimes you need to understand what is happening inside your robot's software. +This article summarizes the ROS developer tools and guidance available to help with introspection. + +**Area: introspection, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +Understanding what is happening inside your robot's software is key to understanding how to improve it. +Introspection tools in ROS allow you to understand and modify, at run-time, node state, parameters, flowing data, and more. +ROS Analysis tools build further on this ability by enabling you to analyze the data gathered by introspection. + +See :doc:`About analysis ` + +Core ROS packages: + +* `ros2 `_: A set of software libraries and tools for building robot applications. + +* `rqt `_: A set of graphical tools for visualizing and interacting with ROS data. + +* `rosbag2 `_: Tool for recording and playing back data moving across topics, services and actions in a ROS application. + +* `rosconsole `_: A logging tool for monitoring, debugging, and diagnosing running applications. + +Community-contributed packages: + +* `colcon `_: Tool for creating and building a ROS workspace. + +* `ament_cmake `_: Build system for CMake-based packages in ROS. + +* `tracetools `_: Trace points for creating and debugging execution traces. + +Related content (placeholder) +----------------------------- + +More articles about introspection: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/About-node-management.rst b/source/About-node-management.rst new file mode 100644 index 00000000000..e0736516720 --- /dev/null +++ b/source/About-node-management.rst @@ -0,0 +1,42 @@ +Node management +=============== + +Sometimes you need to manage many interconnected nodes at once to reliably start, configure, and shut down your system. +Managing multiple interconnected nodes is essential for complex robotic systems. +This article summarizes the ROS developer tools and guidance available to help with node management. + + +**Area: node management, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +Complex robotic systems can include many interconnected nodes, each with different settings and interfaces. +Node management tools in ROS help you start, configure, and stop multiple nodes together using launch files. + +Core ROS packages: + +* `ros2launch `_: Command line tool for launching multiple processes and for writing tests involving multiple processes. +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: +QUESTION FOR THE REVIEWER: ARE THERE ANY COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + +Related content (placeholder) +----------------------------- + +More articles about node management: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/About-package-documentation.rst b/source/About-package-documentation.rst new file mode 100644 index 00000000000..e4ee758d10e --- /dev/null +++ b/source/About-package-documentation.rst @@ -0,0 +1,91 @@ +Package documentation +===================== + +Package documentation is essential for others to understand and use the package you've developed. +This article summarizes the tools and guidance available to help with creating documentation for ROS packages. + +**Area: package documentation, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +-------- + +When creating a new package, clear documentation is essential for others who may use it. +Package documentation tools in ROS make it easy to write, maintain, and generate web-browsable documentation from your source code. + +Core ROS packages: + +* `rosdoc2 `_: Tool for documenting a ROS package. +QUESTION FOR THE REVIEWER: IN THE SPREADSHEET THERE IS A QUESTION MARK NEXT TO THIS ENTRY. +DO WE NEED TO INCLUDE IN THIS LIST? + +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: + +QUESTION FOR THE REVIEWER: ARE THERE ANY COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + + +Package documentation locations +------------------------------- + +ROS package documentation can be found in multiple places. +Here is a brief list of where to look for specific ROS package documentation. + +* Most ROS packages have their package level documentation `included in this index page `_. + +* All ROS package documentation is hosted alongside its information on the `ROS Index `_. + +Searching for packages on ROS Index will yield their information such as released distributions, README.md files, URLs, and other important metadata. + +Larger packages +--------------- + +Larger packages like MoveIt, Nav2, and microROS, are given their own domain or subdomain on ros.org. +Here is a short list. + +* `MoveIt `_ + +* `Navigation2 `_ + +* `Control `_ + +* `microROS (embedded systems) `_ + +API documentation +----------------- + +You can find the API level documentation for the ROS client libraries in the Lyrical distribution using the links below: + +* `rclcpp - C++ client library `_ + +* `rclcpp_lifecycle - C++ lifecycle library `_ + +* `rclcpp_components - C++ components library `_ + +* `rclcpp_action - C++ actions library `_ + +Guidelines for adding your package documentation +------------------------------------------------ + +All released ROS packages are automatically added to docs.ros.org and `ROS Index `_. +If you would like to enable or configure your own package, see `Documenting a ROS package `_. + +Related content (placeholder) +----------------------------- + +More articles about package documentation: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/About-visualization.rst b/source/About-visualization.rst new file mode 100644 index 00000000000..6bf51cbfa31 --- /dev/null +++ b/source/About-visualization.rst @@ -0,0 +1,43 @@ +Visualization +============= + +Sometimes you need to visualize what your robot is sensing and planning to better develop, test, and debug your system. +This article summarizes the ROS developer tools and guidance available to help with visualization. + + +**Area: visualization, tools | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +Understanding what a robot is sensing, experiencing, and planning makes development and debugging much easier. +Visualization tools in ROS help you convert raw robot data into clear, human-readable visual formats. + +Core ROS packages: + +* `RViz `_: Provides a 3D visualization of the robot's perspective, including sensor data and intentions. + +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: + +QUESTION FOR THE REVIEWER: ARE THERE ANY COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + +Related content (placeholder) +----------------------------- + +More articles about visualization: + +* Example + +* Example + +FAQs (placeholder) +------------------ + +* Example + +* Example diff --git a/source/Concepts/Intermediate/About-Debugging.rst b/source/Concepts/Intermediate/About-Debugging.rst new file mode 100644 index 00000000000..8f05945d843 --- /dev/null +++ b/source/Concepts/Intermediate/About-Debugging.rst @@ -0,0 +1,48 @@ +Debugging +========= + +Sometimes your robot won't behave as you expected. This article summarizes the ROS developer tools and guidance available to help with debugging. + +.. contents:: Table of Contents + :local: + +**Area: debugging, tools | Content-type: about | Experience: beginner, intermediate, expert** + +Summary +------- + +ROS provides a range of tools to help developers build, test, and monitor robotic systems. +Debugging is an essential part of development, and many of these tools can be used to identify and fix issues. +Some of the tools are also useful for other aspects of robotic system development. +For example, debugging overlaps with introspection, analysis, node management, visualization, and simulation, as these activities are often used to investigate and diagnose issues in a system. + +Core ROS packages: + +* `ros2doctor `_: Command line tool to check for common misconfigurations in a ROS system. + +* `tracetools `_: Trace points for creating and debugging execution traces. + +* `rosbag2 `_: Record and play back data moving across topics, services and actions in a ROS application, for later visualization and debugging. +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER CORE ROS PACKAGES THAT WE CAN LIST HERE? + +Community-contributed packages: + +* `PlotJuggler `_: A tool for visualizing and analyzing data from ROS applications. +QUESTION FOR THE REVIEWER: ARE THERE ANY OTHER COMMUNITY-CONTRIBUTED PACKAGES THAT WE CAN LIST HERE? + +Related content +--------------- + +More articles about debugging: + +.. + * `Debugging a ROS application - overview `_ + * `Using ros2doctor to identify issues - how-to `_ + * `Building ROS 2 with tracing - how-to `_ + +FAQs (placeholder) +------------------- + +* Example + +* Example diff --git a/source/index.rst b/source/index.rst index 93cbe9d2f4c..eb597aeb563 100644 --- a/source/index.rst +++ b/source/index.rst @@ -22,7 +22,12 @@ ROS 2 Documentation Related-Projects Glossary Citations - + About-introspection + About-analysis + About-node-management + About-builds + About-visualization + About-package-documentation **The Robot Operating System (ROS) is a set of software libraries and tools for building robot applications.** From drivers and state-of-the-art algorithms to powerful developer tools, ROS has the open source tools you need for your next robotics project.