[ros-users] [Discourse.ros.org] [Next Generation ROS] ROS 2 documentation home moving to index.ros.org/doc/ros2

[Tully Foote]

Sorry that extra statement of changing the markdown was poorly edited between the other two sentences.

[quote="tfoote, post:1, topic:6612"]

Like with the rest of the ROS 2 development process this will help us improve the documentation by letting us have it go through the same type of review process that were applying for code changes.

[/quote]



Is a follow up to 

[quote="tfoote, post:1, topic:6612"]

Unlike the wiki, which could be edited by anyone with a Github account, the new content can be edited by opening pull requests against the [ros2/ros2_documentation](https://github.com/ros2/ros2_documentation) repository.

[/quote]



It's actually a significant pain to monitor the github wiki pages for changes that might be at issue. There have been changes that have inserted regressions into the installation instructions that we had to manually go back and correct and ping the author to ask what the reason for the change was and opening a ticket and @ mentioning them is the only way to reach them. Versus if they'd opened a PR against the repo we'd have been notified in our standard development stream, several users could review and give feedback and if more information is needed we can iterate there in the PR thread.



The choice of RST was to support sphinx integration such as [inter-sphinx links](https://github.com/ros-infrastructure/rosindex/pull/85). We would like to and tried to suppport markdown too, but because there were [technical limitations of the markdown integration with sphinx we had to let it go. It's certainly something that can be added back but we don't have the bandwidth to make it work. The ability to have the integrated code references is an important part of our [broader vision](https://github.com/ros2/design/blob/gh-pages/articles/080_ros_documentation_system.md).



Note that this limitation is only for the Doc section and content in the ros2_documentation repository. This Doc section is where we plan to have core tutorials and instructions and documentation but it is not designed to grow significantly beyond the current scope. As linked in our design draft we are working to encourage documentation and tutorials to live with the code following our more federated model. For a given project the maintainer is welcome to pick the markup language of your choice. The index should then provide a place for you to link to it.



Specifically the limitation does not apply to the READMEs that the site renders from the indexed repositories and packages (most of them are in markdown and are rendering just fine, [for example moveit](https://index.ros.org/r/moveit/github-ros-planning-moveit/#melodic)) which I believe will be the majority of the content that users will contribute to the site.











---

[Visit Topic](https://discourse.ros.org/t/ros-2-documentation-home-moving-to-index-ros-org-doc-ros2/6612/3) or reply to this email to respond.