From 4e9617b1f4c25401f2a07bfba3ec6f874f3ca620 Mon Sep 17 00:00:00 2001 From: kscottz Date: Mon, 12 Feb 2024 17:22:11 -0800 Subject: [PATCH 01/11] Migration guide draft. May need to be standalone. --- .../Contributing-To-ROS-2-Documentation.rst | 43 +++++++++++++++++++ 1 file changed, 43 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 307ef350d8f..b061a235a3a 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 @@ -123,6 +123,49 @@ To check for broken links on the site, run: This will check the entire site for broken links, and output the results to the screen and ``build/linkcheck``. +Migrating Pages from the ROS Wiki +--------------------------------- + + +The first step in migrating a page from the `ROS Wiki `_ to the ROS documentationis to determine if the page needs to be migrated. Pages that you or others find useful, and refer to regularly, are good candidates assuming they have not been supersceded by other documentation. +Pages for ROS projects and features that are no longer supported by a current distribution should not be migrated. + +The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. Only Wiki pages that cover core ROS concepts belong on the ROS documentation and these pages should be migrated to a logical location within the ROS documentation. +Package specific documentation should be migrated to the package level documentation generated in the package's source repository. +Once the package level documentation has been updted it will be visible `in this location `_ + +Once you've determined that a page is worth migrating and has an appropriate landing spot in the ROS documentation, the next step in the migration process is to set up the conversion tools necessary to migrate the page. +In most cases the only tools necessary to migrate a single Wiki page to the ROS Docs is `PanDoc `_ and a text editor. +PanDoc is supported by most modern operating systems using the instruction found on their website. +The ROS Wiki uses an older wiki technology that is a competitor to the technology used by Wikipedia, and the markup language is dialect of the MediaWiki format. +We've found that the easiest way to migrate a page from the ROS Wiki is to convert it from HTML into reStructured text using PanDoc. + + +Migrating a Wiki File +^^^^^^^^^^^^^^^^^^^^^ + +#. Create a new Github branch for your migrated page. We suggest something like `pagename-migration`. + +#. Download the appropriate ROS Wiki page to an html file using wget or a similar tool (e.g. `wget -O urdf.html https://wiki.ros.org/urdf`). + +#. Remove the extraneous HTML in the download file. Using your browser's developer mode, find the name of the first useful HTML element in the Wiki page. In most cases all of the HTML between the third line of the file, starting with the `` tag, through the start of the first `

` tag can be safely removed. In the case where there is a table of contents, the first useful tag may be an `

` tag. Similarly, the ROS wiki contains some footer text that starts with `
` and ends just above `` that can be removed. + +#. Find and download any images that may be in the old document. The easiest way to do this is to right click in the browser and download all of the images. Alternatively you can find images by searching for `` tags. + +#. Convert your html file by running a PanDoc conversion between HTML and restructured text. The following command coverts an HTML file to the equivalent reStructured text files. `pandoc -f html -t rst urdf.html > URDF.rst` + +#. Attempt to build your new documentation. There may be errors and warning that you will need to fix. + +#. **CAREFULLY** read through the entire page making sure the material is up-to date for ROS 2. Check every single link to make sure it points to the appropriate location on docs.ros.org. Internal document references must be updated to point to the equivalent ROS 2 material. Unless it is absolutely necessary your updated document should not point to the ROS Wiki and you may need to alter the document considerably by pulling in multiple wiki files. You should verify that every code sample is working correctly under ROS 2. + +#. Add a table of contents to the top of your new rst document. This block should replace any existing table of contents from the wiki.. + +#. Update the image file links to point to the correct image directory for the ROS Docs.. If images require updating, or could be replaced with a Mermaid chart, please make this change. + +#. Issue your pull request. Make sure to point to the original ROS Wiki file for reference. + + + Building the Site with GitHub Codespaces ---------------------------------------- First, you need to have a GitHub account (If you don't have one, you can create one for free). Then, you need to go to the `ROS 2 Documentation GitHub repository `_. After that, you can open the repository in Codespaces, it can be done just by clicking on the "Code" button on the repository page, then choose "Open with Codespaces" from the dropdown menu. From 13492e0f5081c2369d37fd28ea6e00df43c27fd2 Mon Sep 17 00:00:00 2001 From: kscottz Date: Tue, 13 Feb 2024 16:37:28 -0800 Subject: [PATCH 02/11] Cleanup text and markup. --- .../Contributing-To-ROS-2-Documentation.rst | 57 ++++++++++++------- 1 file changed, 37 insertions(+), 20 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 b061a235a3a..ad1da2b4d0d 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 @@ -127,43 +127,60 @@ Migrating Pages from the ROS Wiki --------------------------------- -The first step in migrating a page from the `ROS Wiki `_ to the ROS documentationis to determine if the page needs to be migrated. Pages that you or others find useful, and refer to regularly, are good candidates assuming they have not been supersceded by other documentation. +The first step in migrating a page from the `ROS Wiki `_ to the ROS documentation is to determine if the page needs to be migrated. Pages that you or others find useful, and refer to regularly, are good candidates assuming they have not been supersceded by other documentation. Pages for ROS projects and features that are no longer supported by a current distribution should not be migrated. -The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. Only Wiki pages that cover core ROS concepts belong on the ROS documentation and these pages should be migrated to a logical location within the ROS documentation. -Package specific documentation should be migrated to the package level documentation generated in the package's source repository. -Once the package level documentation has been updted it will be visible `in this location `_ +The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. +Only ROS Wiki pages that cover core ROS concepts belong in the ROS Documentation; these pages should be migrated to a logical location within the ROS documentation. +Package specific documentation should be migrated to the package-level documentation generated in the package's source repository. +Once the package level documentation has been updted it will be visible `as part of the package-level documentation `_ -Once you've determined that a page is worth migrating and has an appropriate landing spot in the ROS documentation, the next step in the migration process is to set up the conversion tools necessary to migrate the page. -In most cases the only tools necessary to migrate a single Wiki page to the ROS Docs is `PanDoc `_ and a text editor. -PanDoc is supported by most modern operating systems using the instruction found on their website. -The ROS Wiki uses an older wiki technology that is a competitor to the technology used by Wikipedia, and the markup language is dialect of the MediaWiki format. +Once you've determined that a ROS Wiki page is worth migrating, and found an appropriate landing spot in the ROS documentation, the next step in the migration process is to set up the conversion tools necessary to migrate the page. +In most cases the only tools necessary to migrate a single ROS Wiki page to the ROS Docs are the `PanDoc `_ command line tool and a text editor. +PanDoc is supported by most modern operating systems using the installation instruction found on their website. +It is worth noting that the ROS Wiki uses an older wiki technology that is a competitor to the technology used by Wikipedia, as such the markup language used is an obscure dialect of the MediaWiki format. We've found that the easiest way to migrate a page from the ROS Wiki is to convert it from HTML into reStructured text using PanDoc. Migrating a Wiki File ^^^^^^^^^^^^^^^^^^^^^ -#. Create a new Github branch for your migrated page. We suggest something like `pagename-migration`. +#. Create a new Github branch for your migrated page. We suggest something like ``pagename-migration``. -#. Download the appropriate ROS Wiki page to an html file using wget or a similar tool (e.g. `wget -O urdf.html https://wiki.ros.org/urdf`). +#. Download the appropriate ROS Wiki page to an html file using wget or a similar tool (e.g. ``wget -O urdf.html https://wiki.ros.org/urdf``). + Alternatively you can use your web browser to save the page's HTML. -#. Remove the extraneous HTML in the download file. Using your browser's developer mode, find the name of the first useful HTML element in the Wiki page. In most cases all of the HTML between the third line of the file, starting with the `` tag, through the start of the first `

` tag can be safely removed. In the case where there is a table of contents, the first useful tag may be an `

` tag. Similarly, the ROS wiki contains some footer text that starts with `
` and ends just above `` that can be removed. - -#. Find and download any images that may be in the old document. The easiest way to do this is to right click in the browser and download all of the images. Alternatively you can find images by searching for `` tags. +#. Next you need to remove the extraneous HTML in the file you downloaded + Using your browser's developer mode, find the name of the first useful HTML element in the Wiki page. + In most cases all of the HTML between the third line of the file, starting with the ```` tag, through the start of the first ``

`` tag can be safely removed. + In the case where there is a table of contents, the first useful tag may be an ``

`` tag. Similarly, the ROS wiki contains some footer text that starts with ``
`` and ends just above ```` that can also be removed. -#. Convert your html file by running a PanDoc conversion between HTML and restructured text. The following command coverts an HTML file to the equivalent reStructured text files. `pandoc -f html -t rst urdf.html > URDF.rst` -#. Attempt to build your new documentation. There may be errors and warning that you will need to fix. +#. Convert your html file by running a PanDoc conversion between HTML and restructured text. + The following command coverts an HTML file to the equivalent reStructured text files: ``pandoc -f html -t rst urdf.html > URDF.rst``. -#. **CAREFULLY** read through the entire page making sure the material is up-to date for ROS 2. Check every single link to make sure it points to the appropriate location on docs.ros.org. Internal document references must be updated to point to the equivalent ROS 2 material. Unless it is absolutely necessary your updated document should not point to the ROS Wiki and you may need to alter the document considerably by pulling in multiple wiki files. You should verify that every code sample is working correctly under ROS 2. - -#. Add a table of contents to the top of your new rst document. This block should replace any existing table of contents from the wiki.. +#. Attempt to build your new documentation using the ``make html`` command. + There may be errors and warnings that you will need to address. -#. Update the image file links to point to the correct image directory for the ROS Docs.. If images require updating, or could be replaced with a Mermaid chart, please make this change. +#. **CAREFULLY** read through the entire page making sure the material is up to date for ROS 2. + Check every single link to make sure it points to the appropriate location on docs.ros.org. + Internal document references must be updated to point to the equivalent ROS 2 material. + Your updated document should not point to the ROS Wiki unless it is absolutely necessary. + This process may require you alter the document considerably, and you may need to pull multiple wiki files. + You should verify that every code sample in the document is working correctly under ROS 2. -#. Issue your pull request. Make sure to point to the original ROS Wiki file for reference. +#. Find and download any images that may be in the old document. The easiest way to do this is to right click in the browser and download all of the images. Alternatively you can find images by searching for ```` tags in the HTML file. +#. For each image files downloaded update the image file links to point to the correct image directory for the ROS Docs. + If any of the images require updating, or could be replaced with a Mermaid chart, please make this change. + +#. Once your document is complete add a table of contents to the top of your new rst document using the appropriate Sphinx commands. + This block should replace any existing table of contents from the old ROS Wiki. + +#. Issue your pull request. + Make sure to point to the original ROS Wiki file for reference. + +#. Once your pull request has been accepted please add a note to the top of the page on the original ROS Wiki article pointing to the new documentation page. Building the Site with GitHub Codespaces From 91044aad23b976b0e199f1e2e02b34bc61e48a52 Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:15:10 -0800 Subject: [PATCH 03/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 8 ++++++-- 1 file changed, 6 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 ad1da2b4d0d..16966efa078 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 @@ -126,8 +126,12 @@ This will check the entire site for broken links, and output the results to the Migrating Pages from the ROS Wiki --------------------------------- - -The first step in migrating a page from the `ROS Wiki `_ to the ROS documentation is to determine if the page needs to be migrated. Pages that you or others find useful, and refer to regularly, are good candidates assuming they have not been supersceded by other documentation. +The first step in migrating a page from the `ROS Wiki `_ to the ROS documentation is to determine if the page needs to be migrated. +Check if the content, or something similar, is available on https://docs.ros.org/en/rolling by searching for related terms. +If it has already been migrated, congratulations! +You are done. +If it hasn't been migrated, then consider whether it is worth keeping. +Pages that you or others find useful, and refer to regularly, are good candidates assuming they have not been superseded by other documentation. Pages for ROS projects and features that are no longer supported by a current distribution should not be migrated. The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. From 35ce93a3691540c6b1e64442488effef65b3223f Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:15:35 -0800 Subject: [PATCH 04/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 16966efa078..302edb7aadb 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 @@ -142,7 +142,7 @@ Once the package level documentation has been updted it will be visible `as part Once you've determined that a ROS Wiki page is worth migrating, and found an appropriate landing spot in the ROS documentation, the next step in the migration process is to set up the conversion tools necessary to migrate the page. In most cases the only tools necessary to migrate a single ROS Wiki page to the ROS Docs are the `PanDoc `_ command line tool and a text editor. PanDoc is supported by most modern operating systems using the installation instruction found on their website. -It is worth noting that the ROS Wiki uses an older wiki technology that is a competitor to the technology used by Wikipedia, as such the markup language used is an obscure dialect of the MediaWiki format. +It is worth noting that the ROS Wiki uses an older wiki technology (MoinMoin), so the markup language used is an obscure dialect of the `MediaWiki `__ format. We've found that the easiest way to migrate a page from the ROS Wiki is to convert it from HTML into reStructured text using PanDoc. From f8d192c77a634f4655e47eb530f948ba80427d53 Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:15:44 -0800 Subject: [PATCH 05/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 302edb7aadb..c5984fd7570 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 @@ -137,7 +137,8 @@ Pages for ROS projects and features that are no longer supported by a current di The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. Only ROS Wiki pages that cover core ROS concepts belong in the ROS Documentation; these pages should be migrated to a logical location within the ROS documentation. Package specific documentation should be migrated to the package-level documentation generated in the package's source repository. -Once the package level documentation has been updted it will be visible `as part of the package-level documentation `_ +Once the package level documentation has been updated it will be visible `as part of the package-level documentation `__. +If you are unsure whether and where to migrate a page, please get in touch via an issue on https://github.com/ros2/ros2_documentation or on https://discourse.ros.org. Once you've determined that a ROS Wiki page is worth migrating, and found an appropriate landing spot in the ROS documentation, the next step in the migration process is to set up the conversion tools necessary to migrate the page. In most cases the only tools necessary to migrate a single ROS Wiki page to the ROS Docs are the `PanDoc `_ command line tool and a text editor. From 9fa9c886d6d11518c3be3e74649b51937a3fbe30 Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:16:04 -0800 Subject: [PATCH 06/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 2 ++ 1 file changed, 2 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 c5984fd7570..d36c6e344c0 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 @@ -150,6 +150,8 @@ We've found that the easiest way to migrate a page from the ROS Wiki is to conve Migrating a Wiki File ^^^^^^^^^^^^^^^^^^^^^ +#. Clone the appropriate repository. If you are migrating a page to the official documentation hosted here, then you should clone https://github.com/ros2/ros2_documentation. + #. Create a new Github branch for your migrated page. We suggest something like ``pagename-migration``. #. Download the appropriate ROS Wiki page to an html file using wget or a similar tool (e.g. ``wget -O urdf.html https://wiki.ros.org/urdf``). From c30412479dc0c8188f916aad5c54ce68ec5030e1 Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:16:11 -0800 Subject: [PATCH 07/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 1 - 1 file changed, 1 deletion(-) 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 d36c6e344c0..7c7c5045218 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 @@ -162,7 +162,6 @@ Migrating a Wiki File In most cases all of the HTML between the third line of the file, starting with the ```` tag, through the start of the first ``

`` tag can be safely removed. In the case where there is a table of contents, the first useful tag may be an ``

`` tag. Similarly, the ROS wiki contains some footer text that starts with ``
`` and ends just above ```` that can also be removed. - #. Convert your html file by running a PanDoc conversion between HTML and restructured text. The following command coverts an HTML file to the equivalent reStructured text files: ``pandoc -f html -t rst urdf.html > URDF.rst``. From 1b87bed797936ca0b2a8b7c219d76512aa687255 Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:16:17 -0800 Subject: [PATCH 08/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Chris Lalancette Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 7c7c5045218..c03964251a9 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 @@ -178,7 +178,7 @@ Migrating a Wiki File #. Find and download any images that may be in the old document. The easiest way to do this is to right click in the browser and download all of the images. Alternatively you can find images by searching for ```` tags in the HTML file. #. For each image files downloaded update the image file links to point to the correct image directory for the ROS Docs. - If any of the images require updating, or could be replaced with a Mermaid chart, please make this change. + If any of the images require updating, or could be replaced with a `Mermaid `__ chart, please make this change. #. Once your document is complete add a table of contents to the top of your new rst document using the appropriate Sphinx commands. This block should replace any existing table of contents from the old ROS Wiki. From 2f415f1ba2dc304abfc13f9cefd5f696dd2c987e Mon Sep 17 00:00:00 2001 From: Katherine Scott Date: Wed, 14 Feb 2024 16:16:44 -0800 Subject: [PATCH 09/11] Update source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst Co-authored-by: Tomoya Fujita Signed-off-by: Katherine Scott --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 c03964251a9..f7e762d377e 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 @@ -135,7 +135,7 @@ Pages that you or others find useful, and refer to regularly, are good candidate Pages for ROS projects and features that are no longer supported by a current distribution should not be migrated. The next step for migrating a ROS Wiki page is to determine the correct location for the migrated page. -Only ROS Wiki pages that cover core ROS concepts belong in the ROS Documentation; these pages should be migrated to a logical location within the ROS documentation. +Only ROS Wiki pages that cover core ROS concepts belong in the ROS Documentation, these pages should be migrated to a logical location within the ROS documentation. Package specific documentation should be migrated to the package-level documentation generated in the package's source repository. Once the package level documentation has been updated it will be visible `as part of the package-level documentation `__. If you are unsure whether and where to migrate a page, please get in touch via an issue on https://github.com/ros2/ros2_documentation or on https://discourse.ros.org. From 31d6d4cb20f7a4f160601bf2a0845264dec6c498 Mon Sep 17 00:00:00 2001 From: kscottz Date: Thu, 15 Feb 2024 14:39:18 -0800 Subject: [PATCH 10/11] Add good example, minor nits. --- .../Contributing/Contributing-To-ROS-2-Documentation.rst | 3 +++ 1 file changed, 3 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 f7e762d377e..8b82a17322d 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 @@ -179,6 +179,7 @@ Migrating a Wiki File #. For each image files downloaded update the image file links to point to the correct image directory for the ROS Docs. If any of the images require updating, or could be replaced with a `Mermaid `__ chart, please make this change. + Be aware that Mermaid.js is only supported in the core ROS 2 documenation currently. #. Once your document is complete add a table of contents to the top of your new rst document using the appropriate Sphinx commands. This block should replace any existing table of contents from the old ROS Wiki. @@ -188,6 +189,8 @@ Migrating a Wiki File #. Once your pull request has been accepted please add a note to the top of the page on the original ROS Wiki article pointing to the new documentation page. +For a real-world example of this process in action, please refer to the ROS 2 Image Processing Pipeline in both `the ROS 2 Docs,`__ and in the original `ROS Wiki`_. +The completed documentation page can be found in the `ROS 2 package documentation for image_pipeline`__. Building the Site with GitHub Codespaces ---------------------------------------- From 2bfe306655c4400cdcfae3e08a6a4aac78c819d3 Mon Sep 17 00:00:00 2001 From: Chris Lalancette Date: Fri, 16 Feb 2024 09:00:15 -0500 Subject: [PATCH 11/11] Style fixes. Signed-off-by: Chris Lalancette --- .../Contributing-To-ROS-2-Documentation.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 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 8b82a17322d..a831e4656df 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 @@ -126,7 +126,7 @@ This will check the entire site for broken links, and output the results to the Migrating Pages from the ROS Wiki --------------------------------- -The first step in migrating a page from the `ROS Wiki `_ to the ROS documentation is to determine if the page needs to be migrated. +The first step in migrating a page from the `ROS Wiki `_ to the ROS 2 documentation is to determine if the page needs to be migrated. Check if the content, or something similar, is available on https://docs.ros.org/en/rolling by searching for related terms. If it has already been migrated, congratulations! You are done. @@ -189,18 +189,21 @@ Migrating a Wiki File #. Once your pull request has been accepted please add a note to the top of the page on the original ROS Wiki article pointing to the new documentation page. -For a real-world example of this process in action, please refer to the ROS 2 Image Processing Pipeline in both `the ROS 2 Docs,`__ and in the original `ROS Wiki`_. -The completed documentation page can be found in the `ROS 2 package documentation for image_pipeline`__. +For a real-world example of this process in action, please refer to the ROS 2 Image Processing Pipeline in both `the ROS 2 Docs `__ and in the original `ROS Wiki `__. +The completed documentation page can be found in the `ROS 2 package documentation for image_pipeline `__. Building the Site with GitHub Codespaces ---------------------------------------- -First, you need to have a GitHub account (If you don't have one, you can create one for free). Then, you need to go to the `ROS 2 Documentation GitHub repository `_. After that, you can open the repository in Codespaces, it can be done just by clicking on the "Code" button on the repository page, then choose "Open with Codespaces" from the dropdown menu. +First, you need to have a GitHub account (if you don't have one, you can create one for free). +Then, you need to go to the `ROS 2 Documentation GitHub repository `__. +After that, you can open the repository in Codespaces, it can be done just by clicking on the "Code" button on the repository page, then choose "Open with Codespaces" from the dropdown menu. .. image:: images/codespaces.png :width: 100% :alt: Codespaces creation -After that, you will be redirected to your Codespaces page, where you can see the progress of the Codespaces creation. Once it is done, a Visual Studio Code tab will be opened in your browser. You can open the terminal by clicking on the "Terminal" tab in the top panel or by pressing :kbd:`Ctrl-J`. +After that, you will be redirected to your Codespaces page, where you can see the progress of the Codespaces creation. +Once it is done, a Visual Studio Code tab will be opened in your browser. You can open the terminal by clicking on the "Terminal" tab in the top panel or by pressing :kbd:`Ctrl-J`. In this terminal, you can run any command you want, for example, you can run the following command to build the site for just this branch: