Sorry that extra statement of changing the markdown was poorly edited between the other two sentences.
Is a follow up to
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. 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.
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) which I believe will be the majority of the content that users will contribute to the site.