Migration guide from ROS Wiki to docs.ros.org #4167
Conversation
There was a problem hiding this comment.
I've left a number of changes inline.
I'm torn about whether to put this in another page. This document is already pretty long, so I don't love adding to it. But it also doesn't really feel natural to make a new page. For now, I'm OK with just adding this to the existing page.
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Outdated
Show resolved
Hide resolved
source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
Show resolved
Hide resolved
|
This pull request has been mentioned on ROS Discourse. There might be relevant details there: https://discourse.ros.org/t/growing-issue-with-ros-documentation/36075/12 |
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Chris Lalancette <clalancette@gmail.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
…umentation.rst Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> Signed-off-by: Katherine Scott <katherineAScott@gmail.com>
There was a problem hiding this comment.
Saw this linked on discourse - looks good. A few other notes:
- If you're looking for an example of a package/repo that has been ported from ROS Wiki to rosdoc2/api docs - I present http://docs.ros.org/en/rolling/p/image_pipeline/ - I just finished porting about 98% of the wiki content last week.
- One of the painful parts I ran into was that the rate limiting on the wiki meant I could only download like 2-3 images at a time.... and there were about 30 in the wiki pages
| #. 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 ``<img src>`` 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 <https://mermaid.js.org/intro/>`__ chart, please make this change. |
There was a problem hiding this comment.
does mermaid work for all packages (i.e. generically with rosdoc2 for api docs?) or just ros core documentation? If just core docs, might want to clarify that
There was a problem hiding this comment.
does mermaid work for all packages (i.e. generically with rosdoc2 for api docs?) or just ros core documentation? If just core docs, might want to clarify that
Good point. Right now, it will only work for the ROS 2 core documentation, so we should be explicit here.
There was a problem hiding this comment.
@mikeferguson you're a saint. We really appreciate it. I guess we could include a longer example.
I don't have a great answer on wiki images. The wiki is held together with tape and bailing wire at this poing. I was considering making a markdown clone of the wiki but I fear it might take the whole edifice to the ground. More to the point, the path the wiki uses for images is a bit weird, I ran into images trying use wget to pull images out the html files.
There was a problem hiding this comment.
Other than @mikeferguson 's suggestions, this looks good to me.
There was a problem hiding this comment.
This looks good to me. Thanks @kscottz for putting this together, and thanks @mikeferguson for beta-testing this, sort of.
clalancette
added
the
backport-all
Signed-off-by: Chris Lalancette <clalancette@gmail.com>
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d) # Conflicts: # source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d) # Conflicts: # source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d)
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d)
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d) Co-authored-by: Katherine Scott <katherineAScott@gmail.com>
* Migration guide. Signed-off-by: Katherine Scott <katherineAScott@gmail.com> Co-authored-by: Chris Lalancette <clalancette@gmail.com> Co-authored-by: Tomoya Fujita <Tomoya.Fujita@sony.com> (cherry picked from commit 8fbb74d) Co-authored-by: Katherine Scott <katherineAScott@gmail.com>
|
This pull request has been mentioned on ROS Discourse. There might be relevant details there: https://discourse.ros.org/t/ros-news-for-the-week-of-february-12th-2024/36135/1 |
|
This pull request has been mentioned on ROS Discourse. There might be relevant details there: |
This pull request adds a short guide on how to migrate a single page from the ROS Wiki to docs.ros.org.
I am working on a plan to sunset the ROS Wiki. I wanted to get a better sense of how best to migrate a pages over. Long story short, I think the best approach for most pages is to manually download a given page and convert it with PanDoc. While this approach has a lot of warts, I think it is probably the best approach as it forces you to manually update / validate every link in the page.
I ran through this approach on a few trivial pages to test it for basic functionality. Once this pull request is merged I intend to migrate a few key pages over.
I realize this guide is quite long. If you would like me to break it out into its own page just let me know.