As many of you are surely aware for a while we’ve been hosting ROS 2 development documentation on a Github wiki under the ROS 2 organization, github.com/ros2/ros2/wiki. This has been a temporary location out of convenience while we have been setting up new infrastructure to host it for the longer term. As we move on with the efforts to improve ROS documentation, we’re now taking the step of moving the ROS 2 wiki to index.ros.org/doc/ros2.
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 repository. Another change is that the documentation is now using the reStructuredText format instead of markdown. 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 we’re applying for code changes.
The wiki links will continue existing, but they now display a notice to their new URLs, and we recommend that you update links within any external documentation you may be hosting.
As an aside, is a soft launch of the new ROS Index site. It is still a beta version under development at ros-infrastructure/rosindex. It’s built on the rosindex from Jon Bohren at Honeybee Robotics and although it’s a fork right now we hope to homogenize it in the future. If you’re interested in contributing, there are several enhancements ticketed. At the moment content is expected to update nightly. As always, we welcome new issues and especially pull requests .
Another change is that the documentation is now using the reStructuredText format instead of markdown. 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 we’re applying for code changes.
Sorry if I missed the requirements doc, but can you better help us understand why reStructuredText was used instead of Markdown? You say its for the “same type of review process” but you can actually have that for either formats. ReStructuredText, however, is a lot more complicated to learn IMHO and is clunky.
Markdown seems to have become the dominant format in recent years due to its simplicity. For example here at Discourse and of course all pull requests and issues at Github.
In reality, since Github is the dominant ROS code hosting platform, using Markdown (what github uses) would let it “go through the same type of review process that we’re applying for code changes”.
For the MoveIt! project, we currently use Markdown for the website and reStructuredText for the tutorials, and the reStructured text and much trickier and people routinely (myself included) make mistakes with it.
I realize that reStructured text allows you to do a lot more complicated Python scripting, but I’m not convinced we need that for the global ROS2 docs. Do you plan on committing code files to this repo as well? Instead I’d prefer increased accessibility for people to contribute, and consistency with what we’re using on Github and Discourse.
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.
I’ll echo what Dave said. While I agree that forcing a formal review of documentation changes is a good idea, I’m not a fan of adding another technology in the form of RST that I have to learn in order to contribute to ROS2.
What I was hoping for was a ROS-specific ticket that says what work would need to be done in order to support Markdown. I imagine there’s some portion of rosindex that needs configuring, but I’m not sure what fork that would be on, or where the particular configurations are.
Yeah, I dunno, maybe one of the people working on that can help. The best thing might be to open an issue asking what needs to be done. I’m not sure that all of them are watching discourse closely.
I’d like contribute, but I’m also still a bit confused about the organizational structure and direction of ROS2 documentation. Given that this is a soft launch, the index site will be the main entry point for ROS 2 documentation, plus the new ros2/ros2_documentation repo, some of my decision paralysis arises from:
What is the expected workflow for contributing new content?
E.g. are there templates I should start from, what are the expected conventions?
With wiki.ros.org, we used templates for adding packages, tutorials, user guide, etc.
How does the previous wiki play into all of this?
How should authors gauge where to host the candidate documentation?
E.g. should it reside with closest related package?
Or when does something warrant being on ros2_documentation?
What if we’re writing about core ROS2 features?
Should it instead be structured the doc folder in the core packages code repo?
How is ros2_documentation versioned over releases and patches?
E.g. allowing users to index through general docs wrt. release history.
If I’m writing about features in a specific release, do we meta-tag it somehow?
There looks to be a related ticked addressing the foreboding flat layout:
I guess ROS has always been a bit different in that is not just one cohesive library, nore is merely a package ecosystem; So its difficult to pin down the documentation model to either a monolithic source of knowledge vs a decoupled sprinkling or context specific notes. Even before the index, I’ve puzzled about the asymmetry of activity and relevance between wiki.ros.org and docs.ros.org.
.