From c2d274501bd92b1c438b14715515b1414ab56836 Mon Sep 17 00:00:00 2001 From: Nils-Christian Iseke Date: Tue, 29 Apr 2025 10:36:31 +0200 Subject: [PATCH 1/2] Updating ROS2-Doc Cotr. Guildelines Signed-off-by: Nils-Christian Iseke --- .../Contributing-To-ROS-2-Documentation.rst | 27 ++++++------------- 1 file changed, 8 insertions(+), 19 deletions(-) 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 7da96f9adcf..30639d5f9ac 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 @@ -476,7 +476,6 @@ Compare the above with a ``bash`` ``code-block``: [INFO] [1742150439.022947971] [my_turtle]: Starting turtlesim with node name /my_turtle [INFO] [1742150439.026043867] [my_turtle]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000] -To simplify code blocks, ``bash`` can still be used without ``$`` for commands meant to be run in a terminal if the code block does not include any output lines. To help choose between ``bash`` and ``console``, see the following list of use-cases and corresponding examples: @@ -489,25 +488,10 @@ To help choose between ``bash`` and ``console``, see the following list of use-c export ROS_DOMAIN_ID=42 ros2 run turtlesim turtlesim_node -#. Commands meant to be run in a terminal *without* any output lines +#. Commands meant to be run in a terminal: - * Use ``.. code-block:: bash`` without ``$``: - - .. code-block:: bash - - source /opt/ros/{DISTRO}/setup.bash - ros2 run turtlesim turtlesim_node - - * Or use ``.. code-block:: console`` with ``$`` on all command lines, i.e., all lines: - - .. code-block:: console - - $ source /opt/ros/{DISTRO}/setup.bash - $ ros2 run turtlesim turtlesim_node - -#. Commands meant to be run in a terminal *with* output lines - - * Use ``.. code-block:: console`` with ``$`` on all command lines: + * Use ``.. code-block:: console`` with ``$`` on all command lines. + If there is output that needs to be displayed, include it in the same block: .. code-block:: console @@ -516,6 +500,11 @@ To help choose between ``bash`` and ``console``, see the following list of use-c [INFO] [1743878028.269334696] [turtlesim]: Starting turtlesim with node name /turtlesim [INFO] [1743878028.275096618] [turtlesim]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000] + .. note:: + + If some output lines start with ``#``, it is crucial to separate commands from their output because the ``#`` symbol is used to denote a command. + Therefore, place the output in a separate ``.. code-block:: text``. + Images ^^^^^^ From de29881bf8f9680e949ddbffa6d20f7d674cc369 Mon Sep 17 00:00:00 2001 From: Tomoya Fujita Date: Tue, 3 Jun 2025 11:39:20 -0700 Subject: [PATCH 2/2] keep the code block policy as preference. Signed-off-by: Tomoya Fujita --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 30639d5f9ac..472a77bcd49 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 @@ -476,7 +476,7 @@ Compare the above with a ``bash`` ``code-block``: [INFO] [1742150439.022947971] [my_turtle]: Starting turtlesim with node name /my_turtle [INFO] [1742150439.026043867] [my_turtle]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000] - +To simplify code blocks, ``bash`` can still be used without ``$`` for commands meant to be run in a terminal if the code block does not include any output lines. To help choose between ``bash`` and ``console``, see the following list of use-cases and corresponding examples: #. Commands meant to be copied into a script file @@ -490,7 +490,7 @@ To help choose between ``bash`` and ``console``, see the following list of use-c #. Commands meant to be run in a terminal: - * Use ``.. code-block:: console`` with ``$`` on all command lines. + * It is highly recommended to use ``.. code-block:: console`` with ``$`` on all command lines for consistency and clarity. If there is output that needs to be displayed, include it in the same block: .. code-block:: console