diff --git a/source/Releases/Release-Eloquent-Elusor.rst b/source/Releases/Release-Eloquent-Elusor.rst index eb16e6fb4c..1abe2e4102 100644 --- a/source/Releases/Release-Eloquent-Elusor.rst +++ b/source/Releases/Release-Eloquent-Elusor.rst @@ -210,13 +210,13 @@ As an example, a command line using Dashing syntax like: .. code-block:: console - ros2 run some_package some_node foo:=bar __params:=/path/to/params.yaml __log_level:=WARN --user-flag + $ ros2 run some_package some_node foo:=bar __params:=/path/to/params.yaml __log_level:=WARN --user-flag is written using Eloquent (and onwards) syntax as: .. code-block:: console - ros2 run some_package some_node --ros-args --remap foo:=bar --params-file /path/to/params.yaml --log-level WARN -- --user-flag + $ ros2 run some_package some_node --ros-args --remap foo:=bar --params-file /path/to/params.yaml --log-level WARN -- --user-flag This explicit syntax affords new features, like single parameter assignment ``--param name:=value``. For further reference and rationale, check the `ROS command line arguments design document <https://design.ros2.org/articles/ros_command_line_arguments.html>`__. diff --git a/source/Releases/Release-Galactic-Geochelone.rst b/source/Releases/Release-Galactic-Geochelone.rst index 92cf202046..a022f5e520 100644 --- a/source/Releases/Release-Galactic-Geochelone.rst +++ b/source/Releases/Release-Galactic-Geochelone.rst @@ -52,9 +52,9 @@ Ability to specify per-logger log levels It is now possible to specify different logging levels for different loggers on the command line: -.. code-block:: bash +.. code-block:: console - ros2 run demo_nodes_cpp talker --ros-args --log-level WARN --log-level talker:=DEBUG + $ ros2 run demo_nodes_cpp talker --ros-args --log-level WARN --log-level talker:=DEBUG The above command sets a global log level of WARN, but sets the log level of the talker node messages to DEBUG. The ``--log-level`` command-line option can be passed an arbitrary number of times to set different log levels for each logger. @@ -94,11 +94,11 @@ Source code generators and interface definition translators are accessible throu For example, given a ``Demo`` message in some ``demo`` package like: -.. code-block:: bash +.. code-block:: console - mkdir -p demo/msg - cd demo - cat << EOF > msg/Demo.msg + $ mkdir -p demo/msg + $ cd demo + $ cat << EOF > msg/Demo.msg std_msgs/Header header geometry_msgs/Twist twist geometry_msgs/Accel accel @@ -106,18 +106,18 @@ For example, given a ``Demo`` message in some ``demo`` package like: it is easy to generate C, C++, and Python support source code: -.. code-block:: bash +.. code-block:: console - rosidl generate -o gen -t c -t cpp -t py -I$(ros2 pkg prefix --share std_msgs)/.. \ + $ rosidl generate -o gen -t c -t cpp -t py -I$(ros2 pkg prefix --share std_msgs)/.. \ -I$(ros2 pkg prefix --share geometry_msgs)/.. demo msg/Demo.msg Generated source code will be put in the ``gen`` directory. One may also translate the message definition to a different format for a third-party code generation tool to consume: -.. code-block:: bash +.. code-block:: console - rosidl translate -o gen --to idl -I$(ros2 pkg prefix --share std_msgs)/.. \ + $ rosidl translate -o gen --to idl -I$(ros2 pkg prefix --share std_msgs)/.. \ -I$(ros2 pkg prefix --share geometry_msgs)/.. demo msg/Demo.msg The translated message definition will be put in the ``gen`` directory. @@ -181,13 +181,13 @@ To see this in action, run the following commands. Terminal 1: -.. code-block:: bash +.. code-block:: console $ ros2 topic pub /chatter std_msgs/msg/String "data: 'hello'" Terminal 2: -.. code-block:: bash +.. code-block:: console $ ros2 topic echo --raw /chatter b'\x00\x01\x00\x00\x06\x00\x00\x00hello\x00\x00\x00' @@ -222,13 +222,13 @@ For example: Terminal 1: -.. code-block:: bash +.. code-block:: console $ ros2 run demo_nodes_cpp parameter_blackboard Terminal 2: -.. code-block:: bash +.. code-block:: console $ ros2 param set /parameter_blackboard foo bar # sets 'foo' parameter to value 'bar' $ ros2 param dump /parameter_blackboard # dumps current value of parameters to ./parameter_blackboard.yaml @@ -244,28 +244,28 @@ Given a publisher and a subscription with `incompatible QoS settings <../../Conc Terminal 1: -.. code-block:: bash +.. code-block:: console $ ros2 run demo_nodes_py talker_qos -n 1000 # i.e. best_effort publisher Terminal 2: -.. code-block:: bash +.. code-block:: console $ ros2 run demo_nodes_py listener_qos --reliable -n 1000 # i.e. reliable subscription ``ros2doctor`` reports: -.. code-block:: bash +.. code-block:: console $ ros2 doctor --report - # ... + ~ ... QOS COMPATIBILITY LIST topic [type] : /chatter [std_msgs/msg/String] publisher node : talker_qos subscriber node : listener_qos compatibility status : ERROR: Best effort publisher and reliable subscription; - # ... + ~ ... while ``rqt_graph`` shows: @@ -328,16 +328,16 @@ To see this in action, you may run these C++ examples (to be found in the `ros2/ Terminal 1: -.. code-block:: bash +.. code-block:: console - ros2 run examples_rclcpp_minimal_publisher publisher_member_function_with_unique_network_flow_endpoints + $ ros2 run examples_rclcpp_minimal_publisher publisher_member_function_with_unique_network_flow_endpoints Terminal 2: -.. code-block:: bash +.. code-block:: console - ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function_with_unique_network_flow_endpoints + $ ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function_with_unique_network_flow_endpoints See the `Unique Network Flows design document <https://github.com/ros2/design/pull/304>`_ for further reference. @@ -351,16 +351,16 @@ Split recording by time In Foxy, you could only split bags as they were recording by the size of the bag, now you can also split by the elapsed time. The following command will split bagfiles into 100-second chunks. -.. code-block:: bash +.. code-block:: console - ros2 bag record --all --max-bag-duration 100 + $ ros2 bag record --all --max-bag-duration 100 ros2 bag list """"""""""""" This new command lists installed plugins of various types that rosbag2 uses. -.. code-block:: bash +.. code-block:: console $ ros2 bag list storage rosbag2_v2 @@ -383,9 +383,9 @@ Compress per-message In Foxy, you could automatically compress each rosbag file as it was split (per-file compression), but now you can also specify per-message compression. -.. code-block:: bash +.. code-block:: console - ros2 bag record --all --compression-format zstd --compression-mode message + $ ros2 bag record --all --compression-format zstd --compression-mode message Rosbag2 Python API @@ -415,15 +415,15 @@ These options may be used together or separately, and in conjunction with ``--al The following command will record only topics with "scan" in the name. -.. code-block:: bash +.. code-block:: console - ros2 bag record --regex "*scan*" + $ ros2 bag record --regex "*scan*" The following command will record all topics except for ones in ``/my_namespace/`` -.. code-block:: bash +.. code-block:: console - ros2 bag record --all --exclude "/my_namespace/*" + $ ros2 bag record --all --exclude "/my_namespace/*" ``ros2 bag reindex`` @@ -440,12 +440,16 @@ New controls have been added for rosbag2 playback - pause & resume, change rate, As of the Galactic release, these controls are exposed only as services on the rosbag2 player node. Development is in progress to expose them to keyboard controls as well in ``ros2 bag play``, but until then a user application with buttons or keyboard controls may be trivially implemented to call these services. -.. code-block:: bash +In one shell: + +.. code-block:: console - # In one shell $ ros2 bag play my_bag - # In another shell +In another shell: + +.. code-block:: console + $ ros2 service list -t /rosbag2_player/get_rate [rosbag2_interfaces/srv/GetRate] /rosbag2_player/is_paused [rosbag2_interfaces/srv/IsPaused] @@ -455,25 +459,44 @@ Development is in progress to expose them to keyboard controls as well in ``ros2 /rosbag2_player/set_rate [rosbag2_interfaces/srv/SetRate] /rosbag2_player/toggle_paused [rosbag2_interfaces/srv/TogglePaused] - # Check if playback is paused $ ros2 service call /rosbag2_player/is_paused rosbag2_interfaces/IsPaused - # Pause playback +To pause playback: + +.. code-block:: console + $ ros2 service call /rosbag2_player/pause rosbag2_interfaces/Pause - # Resume playback +To resume playback: + +.. code-block:: console + $ ros2 service call /rosbag2_player/resume rosbag2_interfaces/Resume - # Change the paused state of playback to its opposite. If playing, pauses. If paused, resumes. +To change the paused state of playback to its opposite. +If playing, pauses. +If paused, resumes. + +.. code-block:: console + $ ros2 service call /rosbag2_player/toggle_paused rosbag2_interfaces/TogglePaused - # Get the current playback rate +To get the current playback rate: + +.. code-block:: console + $ ros2 service call /rosbag2_player/get_rate - # Set the current playback rate (must be > 0) +To set the current playback rate (must be > 0): + +.. code-block:: console + $ ros2 service call /rosbag2_player/set_rate rosbag2_interfaces/SetRate "rate: 0.1" - # Play a single next message (only works while paused) +To play a single next message (only works while paused): + +.. code-block:: console + $ ros2 service call /rosbag2_player/play_next rosbag2_interfaces/PlayNext @@ -483,13 +506,18 @@ Playback publishes /clock Rosbag2 can also dictate "simulation time" by publishing to the ``/clock`` topic during playback. The following commands will publish the clock message at a regular interval. -.. code-block:: bash +To publish at the default rate of 40Hz: + +.. code-block:: console - # Publish at default rate - 40Hz - ros2 bag play my_bag --clock + $ ros2 bag play my_bag --clock - # Publish at specific rate - 100Hz - ros2 bag play my_bag --clock 100 + +To publish at a specific rate, e.g., 100Hz: + +.. code-block:: console + + $ ros2 bag play my_bag --clock 100 Changes since the Foxy release ------------------------------ @@ -579,9 +607,9 @@ This means that the node's namespace will no longer have an effect on the ``/tf` For example: -.. code-block:: bash +.. code-block:: console - ros2 run tf2_ros tf2_echo --ros-args -r __ns:=/test -- odom base_link + $ ros2 run tf2_ros tf2_echo --ros-args -r __ns:=/test -- odom base_link will subscribe to ``/tf`` and ``/tf_static``, as ``ros2 topic list`` will show. @@ -900,9 +928,9 @@ Daemon slows down CLI on Windows As a workaround, CLI commands may be used without a daemon e.g.: -.. code-block:: bash +.. code-block:: console - ros2 topic list --no-daemon + $ ros2 topic list --no-daemon Issue is tracked by `ros2/ros2cli#637 <https://github.com/ros2/ros2cli/issues/637>`_. diff --git a/source/Releases/Release-Humble-Hawksbill.rst b/source/Releases/Release-Humble-Hawksbill.rst index 3a5ebd13f3..8b413c9fa0 100644 --- a/source/Releases/Release-Humble-Hawksbill.rst +++ b/source/Releases/Release-Humble-Hawksbill.rst @@ -774,7 +774,7 @@ The number of matching subscriptions to wait before starting publishing can be c .. code-block:: console - ros2 topic pub -1 -w 3 /chatter std_msgs/msg/String "{data: 'foo'}" + $ ros2 topic pub -1 -w 3 /chatter std_msgs/msg/String "{data: 'foo'}" to wait for three matching subscriptions before starting to publish. @@ -789,17 +789,17 @@ See https://github.com/ros2/ros2cli/pull/642 for more details. It prints to stdout by default: - .. code-block:: bash + .. code-block:: console - ros2 param dump /my_node_name + $ ros2 param dump /my_node_name * ``--output-dir`` option for dump command was `deprecated <https://github.com/ros2/ros2cli/pull/638>`_. To dump parameters to a file, run: - .. code-block:: bash + .. code-block:: console - ros2 param dump /my_node_name > my_node_name.yaml + $ ros2 param dump /my_node_name > my_node_name.yaml ``ros2 param set`` now accepts more YAML syntax """"""""""""""""""""""""""""""""""""""""""""""" diff --git a/source/Releases/Release-Jazzy-Jalisco.rst b/source/Releases/Release-Jazzy-Jalisco.rst index 22f5e0e790..dec0df8281 100644 --- a/source/Releases/Release-Jazzy-Jalisco.rst +++ b/source/Releases/Release-Jazzy-Jalisco.rst @@ -188,9 +188,9 @@ Added a ``--log-file-name`` command line argument It is now possible to use ``--log-file-name`` command line argument to specify the log file name prefix. -.. code-block:: bash +.. code-block:: console - ros2 run demo_nodes_cpp talker --ros-args --log-file-name filename + $ ros2 run demo_nodes_cpp talker --ros-args --log-file-name filename See https://github.com/ros2/ros2cli/issues/856 for more information. @@ -214,9 +214,9 @@ It is now possible to get the number of clients created by a service. It is now possible to use the ``type`` sub-command to check the action type. -.. code-block:: bash +.. code-block:: console - ros2 action type /fibonacci + $ ros2 action type /fibonacci action_tutorials_interfaces/action/Fibonacci See https://github.com/ros2/ros2cli/pull/894 for more information. @@ -235,21 +235,21 @@ And `Service playback <https://github.com/ros2/rosbag2/pull/1481>`__ can play th Record all services data: -.. code-block:: bash +.. code-block:: console - ros2 bag record --all-services + $ ros2 bag record --all-services Record all services and all topic data: -.. code-block:: bash +.. code-block:: console - ros2 bag record --all + $ ros2 bag record --all Play service data from bag file: -.. code-block:: bash +.. code-block:: console - ros2 bag play --publish-service-requests bag_path + $ ros2 bag play --publish-service-requests bag_path See the `design document <https://github.com/ros2/rosbag2/blob/rolling/docs/design/rosbag2_record_replay_service.md>`__ for more information. @@ -258,13 +258,13 @@ New filter modes It is now possible to filter by topic type. -.. code-block:: bash +.. code-block:: console - ros2 bag record --topic_types sensor_msgs/msg/Image sensor_msgs/msg/CameraInfo + $ ros2 bag record --topic_types sensor_msgs/msg/Image sensor_msgs/msg/CameraInfo -.. code-block:: bash +.. code-block:: console - ros2 bag record --topic_types sensor_msgs/msg/Image + $ ros2 bag record --topic_types sensor_msgs/msg/Image See more details https://github.com/ros2/rosbag2/pull/1577 and https://github.com/ros2/rosbag2/pull/1582. diff --git a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst index 89d0524bc0..5f2fdb11ad 100644 --- a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst +++ b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst @@ -48,19 +48,19 @@ And install requirements located in the ``requirements.txt`` file: .. code-block:: console - pip install -r requirements.txt -c constraints.txt + $ pip install -r requirements.txt -c constraints.txt .. group-tab:: macOS .. code-block:: console - pip install -r requirements.txt -c constraints.txt + $ pip install -r requirements.txt -c constraints.txt .. group-tab:: Windows .. code-block:: console - python -m pip install -r requirements.txt -c constraints.txt + $ python -m pip install -r requirements.txt -c constraints.txt In order for Sphinx to be able to generate diagrams, the ``dot`` command must be available. @@ -70,13 +70,13 @@ In order for Sphinx to be able to generate diagrams, the ``dot`` command must be .. code-block:: console - sudo apt update ; sudo apt install graphviz + $ sudo apt update ; sudo apt install graphviz .. group-tab:: macOS .. code-block:: console - brew install graphviz + $ brew install graphviz .. group-tab:: Windows @@ -91,7 +91,7 @@ This is the recommended way to test out local changes. .. code-block:: console - make html + $ make html The build process can take some time. To see the output, open ``build/html/index.html`` in your browser. @@ -104,19 +104,25 @@ You can run the documentation tests locally (using `doc8 <https://github.com/PyC .. code-block:: console - make test + $ make test + +You can run the Python documentation tools tests locally (using `pytest <https://docs.pytest.org/en/stable/>`_) with the following command: + +.. code-block:: console + + $ make test-tools You can run the documentation linter locally (using `sphinx-lint <https://github.com/sphinx-contrib/sphinx-lint>`_) with the following command: .. code-block:: console - make lint + $ make lint You can run the documentation spell checker locally (using `codespell <https://github.com/codespell-project/codespell>`_) with the following command: .. code-block:: console - make spellcheck + $ make spellcheck .. note:: @@ -161,7 +167,7 @@ To check for broken links on the site, run: .. code-block:: console - make linkcheck + $ make linkcheck This will check the entire site for broken links, and output the results to the screen and ``build/linkcheck``. @@ -285,7 +291,7 @@ In this terminal, you can run any command you want, for example, you can run the .. code-block:: console - make html + $ make html Finally, to view the site, you can click on the "Go Live" button in the right bottom panel and then, it will open the site in a new tab in your browser (you will need to browse to the ``build/html`` folder). @@ -305,9 +311,9 @@ Clone repository and start VS Code: .. code-block:: console - git clone https://github.com/ros2/ros2_documentation - cd ./ros2_documentation - code . + $ git clone https://github.com/ros2/ros2_documentation + $ cd ./ros2_documentation + $ code . To use ``Devcontainer``, you need to install "Remote Development" Extension within VS Code search in Extensions (CTRL+SHIFT+X) for it. @@ -320,7 +326,7 @@ Inside the terminal, you can build the documentation: .. code-block:: console - make html + $ make html .. image:: images/vscode_devcontainer.png :width: 100% diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index e990b1dea2..c5f4a4ab95 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -882,47 +882,47 @@ How to measure coverage locally using lcov (Ubuntu) To measure coverage on your own machine, install ``lcov``. -.. code-block:: bash +.. code-block:: console - sudo apt install -y lcov + $ sudo apt install -y lcov The rest of this section assumes you are working from your colcon workspace. Compile in debug with coverage flags. Feel free to use colcon flags to target specific packages. -.. code-block:: bash +.. code-block:: console - colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} --coverage" -DCMAKE_C_FLAGS="${CMAKE_C_FLAGS} --coverage" + $ colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} --coverage" -DCMAKE_C_FLAGS="${CMAKE_C_FLAGS} --coverage" ``lcov`` requires an initial baseline, which you can produce with the following command. Update the output file location for your needs. -.. code-block:: bash +.. code-block:: console - lcov --no-external --capture --initial --directory . --output-file ~/ros2_base.info + $ lcov --no-external --capture --initial --directory . --output-file ~/ros2_base.info Run tests for the packages that matter for your coverage measurements. For example, if measuring ``rclcpp`` also with ``test_rclcpp`` -.. code-block:: bash +.. code-block:: console - colcon test --packages-select rclcpp test_rclcpp + $ colcon test --packages-select rclcpp test_rclcpp Capture the lcov results with a similar command this time dropping the ``--initial`` flag. -.. code-block:: bash +.. code-block:: console - lcov --no-external --capture --directory . --output-file ~/ros2.info + $ lcov --no-external --capture --directory . --output-file ~/ros2.info Combine the trace ``.info`` files: -.. code-block:: bash +.. code-block:: console - lcov --add-tracefile ~/ros2_base.info --add-tracefile ~/ros2.info --output-file ~/ros2_coverage.info + $ lcov --add-tracefile ~/ros2_base.info --add-tracefile ~/ros2.info --output-file ~/ros2_coverage.info Generate html for easy visualization and annotation of covered lines. -.. code-block:: bash +.. code-block:: console - mkdir -p coverage - genhtml ~/ros2_coverage.info --output-directory coverage + $ mkdir -p coverage + $ genhtml ~/ros2_coverage.info --output-directory coverage