From 702479f240e852db4f0b4741601016e6518a2c47 Mon Sep 17 00:00:00 2001 From: kscottz Date: Mon, 3 Feb 2025 15:31:48 -0800 Subject: [PATCH 1/3] Suggested additions from contributor. --- .../Contributing-To-ROS-2-Documentation.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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 c2be93c7b6..d3dac88da4 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 @@ -278,6 +278,11 @@ Writing pages The ROS 2 documentation website uses the ``reStructuredText`` format, which is the default plaintext markup language used by Sphinx. This section is a brief introduction to ``reStructuredText`` concepts, syntax, and best practices. +**When formatting your ``reStructuredText`` file please make sure to write only one sentence per line as it makes reviewing and modifying your file much easier.** +Also, be mindful of the use of white space in your file! +The ROS 2 documentation linter will not accept pull requests with trailing white space. +We recommend that you enable automatic white space highlighting and or cleanup if your editor supports it. + You can refer to `reStructuredText User Documentation `_ for a detailed technical specification. @@ -383,6 +388,13 @@ Images can be inserted using the ``.. image::`` directive. .. image:: images/turtlesim_follow1.png +Charts, Graphs, and Diagrams +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ROS 2 Documentation now supports charts, graphs, and diagrams written using `Mermaid Charts.`__ +We prefer that charts, graphs, and diagrams use Mermaid instead of static image files as it allows us to programmatically update and edit these resources as the project evolves. +Full documentation of the `Mermaid graph language syntax can be found on their website.`__ + References and Links ^^^^^^^^^^^^^^^^^^^^ From 94d5227c55acc1b1001d66c7a22b9fad1ad7c5e3 Mon Sep 17 00:00:00 2001 From: kscottz Date: Mon, 3 Feb 2025 15:50:48 -0800 Subject: [PATCH 2/3] I think this is the formatting it wants. --- .../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 d3dac88da4..ac16c5a276 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 @@ -391,9 +391,9 @@ Images can be inserted using the ``.. image::`` directive. Charts, Graphs, and Diagrams ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ROS 2 Documentation now supports charts, graphs, and diagrams written using `Mermaid Charts.`__ +The ROS 2 Documentation now supports charts, graphs, and diagrams written using `Mermaid Charts. `__ We prefer that charts, graphs, and diagrams use Mermaid instead of static image files as it allows us to programmatically update and edit these resources as the project evolves. -Full documentation of the `Mermaid graph language syntax can be found on their website.`__ +Full documentation of the `Mermaid graph language syntax can be found on their website. `__ References and Links ^^^^^^^^^^^^^^^^^^^^ From 241968a8802e79ef7a962304258daf5aab8f79ef Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Tue, 4 Feb 2025 08:15:07 -0800 Subject: [PATCH 3/3] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Christophe Bedard Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 3 +-- 1 file changed, 1 insertion(+), 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 ac16c5a276..feb32d8a28 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 @@ -278,12 +278,11 @@ Writing pages The ROS 2 documentation website uses the ``reStructuredText`` format, which is the default plaintext markup language used by Sphinx. This section is a brief introduction to ``reStructuredText`` concepts, syntax, and best practices. -**When formatting your ``reStructuredText`` file please make sure to write only one sentence per line as it makes reviewing and modifying your file much easier.** +When formatting your ``reStructuredText`` file **please make sure to write only one sentence per line as it makes reviewing and modifying your file much easier.** Also, be mindful of the use of white space in your file! The ROS 2 documentation linter will not accept pull requests with trailing white space. We recommend that you enable automatic white space highlighting and or cleanup if your editor supports it. - You can refer to `reStructuredText User Documentation `_ for a detailed technical specification. Table of Contents